handler 0.8.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/CHANGELOG.rdoc

@@ -0,0 +1,8 @@
+= Changelog
+
+Per-release changes to Handler.
+
+
+== 0.8.0 (2009 Oct 12)
+
+First release.

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Alex Reisner
+
+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.rdoc

@@ -0,0 +1,35 @@
+= Handler
+
+Handler is a Rails plugin that generates handles (filesystem- and URL-friendly names) for ActiveRecord models based on a given attribute or method. For example, in your model:
+
+  handle_based_on :title
+
+creates a generate_handle method which returns a lowercase ASCII version of the title attribute, for example:
+
+  "Häagen Dazs"             --> "haagen_dazs"
+  ".38 Special"             --> "38_special"
+  "Guns N' Roses"           --> "guns_n_roses"
+  "Emerson, Lake & Palmer"  --> "emerson_lake_and_palmer"
+
+By default the word separator is "_" but you can change this with the <tt>:separator</tt> option, for example:
+
+  handle_based_on :title, :separator => "-"
+
+Transliteration using reasonable ASCII approximations of non-ASCII characters is attempted, using the excellent unidecode gem (http://rubyforge.org/projects/unidecode) if it's available (recommended: <tt>sudo gem install unidecode</tt>).
+
+Usually you want handles to be unique but if they're generated automatically you can't very well use ActiveRecord validation. Instead Handler will append numbers (starting with 2) to duplicate handles, so if you already have a Person with handle <tt>george_brett</tt>, a new Person with name "George Brett" will receive the handle <tt>george_brett_2</tt>. To disable this feature (and allow duplicate handles):
+
+  handle_based_on :name, :unique => false
+
+Handler doesn't store handles automatically, but provides a private method <tt>assign_handle</tt> you can call to do so. Intended use is something like this:
+
+  before_save :assign_handle
+
+By default the handle is written to the <tt>handle</tt> attribute but you can change this like so:
+
+  handle_based_on :name, :write_to => :alias
+
+The above will store the handle as the <tt>alias</tt> attribute.
+
+
+Copyright (c) 2009 Alex Reisner, released under the MIT license

data/Rakefile

@@ -0,0 +1,56 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name        = "handler"
+    gem.summary     = %Q{Handler generates filesystem- and URL-friendly names for ActiveRecord models.}
+    gem.description = %Q{Handler is a Rails plugin that generates handles (filesystem- and URL-friendly names) for ActiveRecord models based on a given attribute or method.}
+    gem.email       = "alex@alexreisner.com"
+    gem.homepage    = "http://github.com/alexreisner/handler"
+    gem.authors     = ["Alex Reisner"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "Handler #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.8.0

data/handler.gemspec

@@ -0,0 +1,51 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{handler}
+  s.version = "0.8.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Alex Reisner"]
+  s.date = %q{2009-10-13}
+  s.description = %q{Handler is a Rails plugin that generates handles (filesystem- and URL-friendly names) for ActiveRecord models based on a given attribute or method.}
+  s.email = %q{alex@alexreisner.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "CHANGELOG.rdoc",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "handler.gemspec",
+     "init.rb",
+     "lib/handler.rb",
+     "test/handler_test.rb",
+     "test/test_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/alexreisner/handler}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Handler generates filesystem- and URL-friendly names for ActiveRecord models.}
+  s.test_files = [
+    "test/handler_test.rb",
+     "test/test_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require 'handler'

data/lib/handler.rb

@@ -0,0 +1,127 @@
+module Handler
+	
+  ##
+  # Included hook: extend including class.
+  #
+  def self.included(base)
+    base.extend ClassMethods
+  end
+  
+  ##
+  # Transliterate a string: change accented Unicode characters to ASCII
+  # approximations. Tries several methods, attempting the best first:
+  # 
+  # 1. unidecode, if installed (http://rubyforge.org/projects/unidecode)
+  # 2. iconv (included with Ruby, doesn't work with all Ruby versions)
+  # 3. normalize, then remove un-normalizable characters
+  #
+  def self.transliterate(string)
+    transliterate_with_unidecode(string) or
+      transliterate_with_iconv(string) or
+      transliterate_with_normalization(string) or
+      string
+  end
+  
+  ##
+  # Transliterate a string with the unidecode library.
+  # Return nil if unsuccessful (eg, library not available).
+  #
+  def self.transliterate_with_unidecode(string)
+    begin
+      require 'unidecode'
+      string.to_ascii
+    rescue LoadError
+      nil
+    end
+  end
+  
+  ##
+  # Transliterate a string with the iconv library.
+  # Return nil if unsuccessful (eg, library not available).
+  #
+  def self.transliterate_with_iconv(string)
+    begin
+      Iconv.iconv('ascii//ignore//translit', 'utf-8', string).to_s
+    rescue
+      nil
+    end
+  end
+  
+  ##
+  # Generate a handle from a string.
+  #
+  def self.generate_handle(title, separator)
+    str = title
+    return nil unless str.is_a?(String)
+    str = transliterate(str).to_s
+    str = str.downcase
+    str = str.strip
+    str = str.gsub('&', ' and ') # add space for, e.g., "Y&T"
+    str = str.delete('.\'"')     # no space
+    str = str.gsub(/\W/, ' ')    # space
+    str = str.gsub(/ +/, separator)
+    str   
+  end
+  
+  ##
+  # Get the next handle in the sequence (for avoiding duplicates).
+  #
+  def self.next_handle(handle, separator)
+    if handle =~ /#{separator}\d+$/
+      handle.sub(/\d+$/){ |i| i.to_i + 1 }
+    else
+      handle + separator + "2"
+    end
+  end
+  
+  ##
+  # Transliterate a string using multibyte normalization,
+  # then remove remaining non-ASCII characters. Taken from
+  # <tt>ActiveSupport::Inflector.transliterate</tt>.
+  #
+  def self.transliterate_with_normalization(string)
+    string.mb_chars.normalize.gsub(/[^\x00-\x7F]+/, '').to_s
+  end
+  
+  module ClassMethods
+  
+    ##
+    # Declare that a model generates a handle based on
+    # a given attribute or method. Options include:
+    # 
+    # <tt>:separator</tt> - character to place between words
+    # <tt>:store</tt> - attribute in which to store handle
+    # <tt>:unique</tt> - generate a handle which is unique among all records
+    #
+    def handle_based_on(attribute, options = {})
+      options[:separator] ||= "_"
+      options[:write_to]  ||= :handle
+      options[:unique]      = true if options[:unique].nil?
+
+	    ##
+	    # Generate a URL-friendly name.
+	    #
+      define_method :generate_handle do
+        h = Handler.generate_handle(send(attribute), options[:separator])
+        if options[:unique]
+          
+          # increase number while *other* records exist with the same handle
+          # (record might be saved and should keep its handle)
+          while self.class.all(:conditions => ["#{options[:write_to]} = ? AND id != ?", h, id]).size > 0
+            h = Handler.next_handle(h, options[:separator])
+          end
+        end
+        h
+      end
+      
+      ##
+      # Assign the generated handle to the specified attribute.
+      #
+      define_method :assign_handle do
+        write_attribute(options[:write_to], generate_handle)
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.class_eval{ include Handler }

data/test/handler_test.rb

@@ -0,0 +1,94 @@
+require 'test_helper'
+
+class HandlerTest < ActiveSupport::TestCase
+
+  test "transliteration" do
+    a = Band.new
+    a.name = "Häagen Dazs"
+    possibilities = [
+      "haagen_dazs", # output of unidecode or normalization
+      "hagen_dazs",  # output of iconv
+    ]
+    assert possibilities.include?(a.generate_handle)
+  end
+
+  test "custom separator" do
+    a = Person.new
+    a.name = "Muddy Waters"
+    assert_equal "muddy-waters", a.generate_handle
+  end
+
+  test "punctuation replacement" do
+    b = Band.new
+    {
+      ".38 Special"                 => "38_special",
+      "Guns N' Roses"               => "guns_n_roses",
+      "The Rossington-Collins Band" => "the_rossington_collins_band"
+      
+    }.each do |s,t|
+      b.name = s
+      assert_equal t, b.generate_handle
+    end
+  end
+
+  test "ampersand replacement" do
+    b = Band.new
+    {
+      "Y&T"                    => "y_and_t",
+      "Huey Lewis & the News"  => "huey_lewis_and_the_news",
+      "Emerson, Lake & Palmer" => "emerson_lake_and_palmer"
+      
+    }.each do |s,t|
+      b.name = s
+      assert_equal t, b.generate_handle
+    end
+  end
+  
+  test "next handle" do
+    assert_equal "banana_boat_2",  Handler.next_handle("banana_boat",    "_")
+    assert_equal "banana-boat-3",  Handler.next_handle("banana-boat-2",  "-")
+    assert_equal "banana-boat-12", Handler.next_handle("banana-boat-11", "-")
+  end
+  
+  test "unique handle generation" do
+    p = Person.new
+    p.name = "Captain Beefheart"
+    assert_equal "captain-beefheart-2", p.generate_handle
+    p.name = "Abe Lincoln"
+    assert_equal "abe-lincoln-4", p.generate_handle
+  end
+end
+
+class ActiveRecordSimulator
+  include Handler
+  attr_accessor :name
+  
+  # simulate id method
+  def id; 123; end
+
+  # simulate ActiveRecord::Base.all method;
+  # needed for testing whether records exist with a given handle
+  def self.all(options)
+    @existing_handles.include?(options[:conditions][1]) ? [nil, nil] : []
+  end
+end
+
+class Band < ActiveRecordSimulator
+  handle_based_on :name
+  @existing_handles = [
+    "the_residents",
+    "bing_crosby"
+  ]
+end
+
+class Person < ActiveRecordSimulator
+  handle_based_on :name, :separator => "-"
+  @existing_handles = [
+    "van-dyke-parks",
+    "captain-beefheart",
+    "abe-lincoln",
+    "abe-lincoln-2",
+    "abe-lincoln-3"
+  ]
+end
+

data/test/test_helper.rb

@@ -0,0 +1,11 @@
+require 'rubygems'
+require 'active_support'
+require 'active_support/test_case'
+require 'test/unit'
+
+# required to avoid errors
+module ActiveRecord
+  class Base; end
+end
+require 'handler'
+

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification 
+name: handler
+version: !ruby/object:Gem::Version 
+  version: 0.8.0
+platform: ruby
+authors: 
+- Alex Reisner
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-13 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: Handler is a Rails plugin that generates handles (filesystem- and URL-friendly names) for ActiveRecord models based on a given attribute or method.
+email: alex@alexreisner.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .gitignore
+- CHANGELOG.rdoc
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- handler.gemspec
+- init.rb
+- lib/handler.rb
+- test/handler_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/alexreisner/handler
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Handler generates filesystem- and URL-friendly names for ActiveRecord models.
+test_files: 
+- test/handler_test.rb
+- test/test_helper.rb