acts_as_label 0.1.0

data/.gitignore

@@ -0,0 +1 @@
+.DS_Store

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Coroutine LLC
+
+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,48 @@
+= acts_as_label
+
+
+== Description
+
+This acts_as extension implements a system label and a friendly label on a class and centralizes
+the logic for performing validations and accessing items by system label.
+
+
+
+== Usage
+
+If you just want validations and system label accessors, simply add acts_as_label to the model.
+
+  class Role < ActiveRecord::Base
+    acts_as_label
+  end
+	
+	
+The plugin accepts three optional parameters.
+
++system_label_column+:: specifies the name of the column to use for the system label (default: system_label)
++label_column+:: specifies the name of the column to use for the label (default: label)
++default+:: specifies the system label value to use as the default record
+
+  class Role < ActiveRecord::Base
+    acts_as_label :system_label_column => :key, :label_column => :name, :default => :guest
+  end
+
+
+If you use the plugin within a single table inheritance (STI) design, the easiest way to specify a default
+record is by implementing a class method on the subclass.
+
+  class Label < ActiveRecord::Base
+    acts_as_label
+  end
+	
+  class BillingFrequency < Label
+    self.default
+      BillingFrequency.monthly
+    end
+  end
+
+
+
+== License
+
+Copyright (c) 2010 Coroutine LLC, released under the MIT license

data/Rakefile

@@ -0,0 +1,43 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'jeweler'
+
+
+desc 'Default: run tests.'
+task :default => [:test]
+
+
+desc 'Test the plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+
+desc 'Generate documentation for the plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'acts_as_label'
+  rdoc.options << '--line-numbers --inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+begin
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name              = "acts_as_label"
+    gemspec.summary           = "Gem version of acts_as_label Rails plugin."
+    gemspec.description       = "This acts_as extension implements a system label and a friendly label on a class and centralizes the logic for performing validations and accessing items by system label."
+    gemspec.email             = "jdugan@coroutine.com"
+    gemspec.homepage          = "http://github.com/coroutine/acts_as_label"
+    gemspec.authors           = ["John Dugan"]
+    gemspec.add_dependency "activesupport"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/init.rb

@@ -0,0 +1,5 @@
+require 'acts_as_label'
+
+ActiveRecord::Base.class_eval do
+  include Coroutine::Acts::Label
+end

data/lib/acts_as_label.rb

@@ -0,0 +1,164 @@
+module Coroutine                      #:nodoc:
+  module Acts                         #:nodoc:
+    module Label                      #:nodoc: 
+
+      def self.included(base)         #:nodoc:
+        base.extend(ClassMethods)
+      end
+
+      
+      module ClassMethods
+      
+        
+        # == Description
+        #
+        # This +acts_as+ extension implements a system label and a friendly label on a class and centralizes
+        # the logic for performing validations and accessing items by system label.
+        #
+        #
+        # == Usage
+        #
+        # Simple Example
+        #
+        #   class BillingFrequency < ActiveRecord::Base
+        #     has_many :subscriptions
+        #     acts_as_label :default => :monthly
+        #   end
+        #
+        #   class Subscription < ActiveRecord::Base
+        #     belongs_to :billing_frequency
+        #   end
+        #
+        #   subscription.billing_frequency = BillingFrequency.monthly
+        #   subscription.billing_frequency = BillingFrequency.default
+        #
+        #
+        # STI Example:
+        #
+        #   class Label < ActiveRecord::Base
+        #     acts_as_label :scoped_to => :type
+        #   end
+        #
+        #   class BillingFrequency < Label
+        #     has_many :subscriptions
+        #     def self.default
+        #       BillingFrequency.monthly
+        #     end
+        #   end
+        #
+        #   class Subscription < ActiveRecord::Base
+        #     belongs_to :billing_frequency
+        #   end
+        #
+        #   subscription.billing_frequency = BillingFrequency.monthly
+        #   subscription.billing_frequency = BillingFrequency.default
+        #
+        #
+        # == Configuration
+        #
+        # * +system_label_cloumn+ - specifies the column name to use for storing the system label (default: +system_label+)
+        # * +label_column+ - specifies the column name to use for storing the label (default: +label+)
+        # * +default+ - specifies the system label value of the default instance (default: the first record in the default scope)
+        # 
+        def acts_as_label(options = {})
+          
+          #-------------------------------------------
+          # scrub options
+          #-------------------------------------------
+          options       = {} unless options.is_a?(Hash)
+          system_label  = options.key?(:system_label_column)  ? options[:system_label_column].to_sym  : :system_label
+          label         = options.key?(:label_column)         ? options[:label_column].to_sym         : :label
+          scope         = options.key?(:scope)                ? options[:scope]                       : "1 = 1"
+          default       = options.key?(:default)              ? options[:default].to_sym              : nil
+                    
+          
+          #--------------------------------------------
+          # mix methods into class definition
+          #--------------------------------------------
+          class_eval do
+            
+            # Add inheritable accessors
+            write_inheritable_attribute :acts_as_label_system_label_column,   system_label
+            class_inheritable_reader    :acts_as_label_system_label_column
+            write_inheritable_attribute :acts_as_label_label_column,          label
+            class_inheritable_reader    :acts_as_label_label_column
+            write_inheritable_attribute :acts_as_label_scope,                 scope
+            class_inheritable_reader    :acts_as_label_scope
+            write_inheritable_attribute :acts_as_label_default_system_label,  default
+            class_inheritable_reader    :acts_as_label_default_system_label
+          
+            
+            # Add validations
+            validates_presence_of       system_label
+            validates_length_of         system_label,  :maximum   => 255
+            validates_format_of         system_label,  :with      => /^[A-Z][_A-Z0-9]*$/
+            validates_presence_of       label
+            validates_length_of         label,         :maximum => 255
+            
+            
+            # Add method missing, if needed
+            unless self.method_defined? :method_missing
+              def self.method_missing(method, *args, &block)
+                super
+              end
+            end
+            
+            # Add custom method missing functionality to perform find by system label lookup. If 
+            # nothing is found, it delegates the call to the original method_missing.
+            def self.method_missing_with_label(method, *args, &block)
+              record =  self.find(:first, :conditions => ["#{acts_as_label_system_label_column} = ?", method.to_s.upcase])
+              if record
+                return record
+              else
+                method_missing_without_label(method, *args, &block)
+              end
+            end
+            
+            # Add method missing alias
+            class << self
+              alias_method_chain :method_missing, :label       
+            end
+               
+            # Add class method to return default record, if needed
+            unless self.method_defined? :default
+              if default.nil?
+                def self.default
+                  self.first
+                end
+              else
+                def self.default
+                  self.send("#{acts_as_label_default_system_label}")
+                end
+              end
+            end
+            
+            
+            # Add all the instance methods
+            include Coroutine::Acts::Label::InstanceMethods
+
+          end
+        end  
+      end
+
+    
+      module InstanceMethods
+      
+        # This method updates the system label attribute writer to ensure it is uppercase.
+        #
+        def system_label=(value)
+          value = value.to_s.strip.upcase unless value.nil?
+          write_attribute("#{acts_as_label_system_label_column}", value)
+        end
+        
+        
+        # This method overrides the to_s method to return the friendly label value.
+        #
+        def to_s
+          self.send("#{acts_as_label_label_column}")
+        end
+        
+      end
+    
+    end
+  end
+end

data/test/acts_as_label_test.rb

@@ -0,0 +1,259 @@
+#---------------------------------------------------------
+# Requirements
+#---------------------------------------------------------
+
+# all generic requirements are in the helper
+require "test/test_helper"
+
+
+
+#---------------------------------------------------------
+# Database config
+#---------------------------------------------------------
+
+# establish db connection
+ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :database => ":memory:")
+
+
+# define and seed tables
+def setup_db
+  ActiveRecord::Schema.define(:version => 1) do
+    create_table :labels do |t|
+      t.string  :type,          :limit => 255
+      t.string  :system_label,  :limit => 255
+      t.string  :label,         :limit => 255
+      
+      t.timestamps
+    end
+    
+    create_table :frameworks do |t|
+      t.string  :system_name,   :limit => 255
+      t.string  :name,          :limit => 255
+      
+      t.timestamps
+    end
+  end
+  
+  Role.create!({ :system_label => "SUPERUSER",  :label => "Admin" })
+  Role.create!({ :system_label => "EMPLOYEE",   :label => "Employee" })
+  Role.create!({ :system_label => "GUEST",      :label => "Guest" })
+  
+  BillingFrequency.create!({ :system_label => "MONTHLY",    :label => "Monthly" })
+  BillingFrequency.create!({ :system_label => "QUARTERLY",  :label => "Quarterly" })
+  BillingFrequency.create!({ :system_label => "YEARLY",     :label => "Yearly" })
+  
+  TaxFrequency.create!({ :system_label => "MONTHLY",    :label => "Monthly" })
+  TaxFrequency.create!({ :system_label => "QUARTERLY",  :label => "Quarterly" })
+  TaxFrequency.create!({ :system_label => "YEARLY",     :label => "Yearly" })
+  
+  Framework.create!({ :system_name => "RUBY_ON_RAILS",  :name => "Rails" })
+  Framework.create!({ :system_name => "DJANGO",         :name => "Django" })
+end
+
+
+# drop all tables
+def teardown_db
+  ActiveRecord::Base.connection.tables.each do |table|
+    ActiveRecord::Base.connection.drop_table(table)
+  end
+end
+
+
+
+#---------------------------------------------------------
+# Model definitions
+#---------------------------------------------------------
+
+# Labels (STI base)
+class Label < ActiveRecord::Base
+  acts_as_label
+end
+
+
+# Roles (STI extension with default)
+class Role < Label
+  def self.default
+    Role.guest
+  end
+end
+
+
+# BillingFrequency (STI extension without default)
+class BillingFrequency < Label
+  validates_uniqueness_of :system_label, :scope => :type
+end
+
+
+# TaxFrequency (STI extension for testing duplicate system labels)
+class TaxFrequency < Label
+  validates_uniqueness_of :system_label, :scope => :type
+end
+
+
+# Frameworks (stand-alone model with overrides)
+class Framework < ActiveRecord::Base
+  acts_as_label :system_label_column => :system_name, :label_column => :name, :default => :ruby_on_rails
+end
+
+
+
+#---------------------------------------------------------
+# Tests
+#---------------------------------------------------------
+
+class ActsAsLabelTest < ActiveSupport::TestCase
+
+  #---------------------------------------------
+  # setup and teardown delegations
+  #---------------------------------------------
+  
+  def setup
+    setup_db
+  end
+  def teardown
+    teardown_db
+  end
+
+
+
+  #---------------------------------------------
+  # test validations
+  #---------------------------------------------
+  
+  def test_validations_with_standard_columns
+    
+    # get valid record
+    record = Role.new({ :system_label => "CUSTOMER",  :label => "Client" })
+    assert record.valid?
+    
+    # system label cannot be null
+    record.system_label = nil               
+    assert !record.valid?
+    
+    # system label cannot be blank
+    record.system_label = ""               
+    assert !record.valid?
+    
+    # system label cannot be longer than 255 characters
+    record.system_label = ""                
+    256.times { record.system_label << "x" }
+    assert !record.valid?
+    
+    # system label cannot have illegal characters
+    record.system_label = "SUPER-USER"
+    assert !record.valid?
+    
+    # reset system label
+    record.system_label = "CUSTOMER"
+    assert record.valid?
+    
+    # label cannot be null
+    record.label = nil               
+    assert !record.valid?
+     
+    # label cannot be blank
+    record.label = ""               
+    assert !record.valid?
+    
+    # label cannot be longer than 255 characters
+    record.label = ""                
+    256.times { record.label << "x" }
+    assert !record.valid?
+    
+  end
+  
+  
+  def test_validations_with_custom_columns
+    
+    # get valid record
+    record = Framework.new({ :system_name => "SPRING",  :name => "Spring" })
+    assert record.valid?
+    
+    # system name cannot be null
+    record.system_name = nil               
+    assert !record.valid?
+    
+    # system name cannot be blank
+    record.system_name = ""               
+    assert !record.valid?
+    
+    # system name cannot be longer than 255 characters
+    record.system_name = ""                
+    256.times { record.system_name << "x" }
+    assert !record.valid?
+    
+    # system name cannot have illegal characters
+    record.system_name = "SPRING-JAVA"
+    assert !record.valid?
+    
+    # reset system name
+    record.system_name = "SPRING"
+    assert record.valid?
+    
+    # name cannot be null
+    record.name = nil               
+    assert !record.valid?
+     
+    # name cannot be blank
+    record.name = ""               
+    assert !record.valid?
+    
+    # name cannot be longer than 255 characters
+    record.name = ""                
+    256.times { record.name << "x" }
+    assert !record.valid?
+    
+  end
+  
+  
+  #---------------------------------------------
+  # test method missing
+  #---------------------------------------------
+  
+  def test_method_missing_accessors
+    
+    # test lookup by system label
+    assert_equal Role.find(:first, :conditions => ["system_label = ?", "SUPERUSER"]), Role.superuser
+    
+    # test default with implemented method
+    assert_equal Role.find(:first, :conditions => ["system_label = ?", "GUEST"]), Role.default
+    
+    # test default with unspecified behavior
+    assert_equal BillingFrequency.first, BillingFrequency.default
+    
+    # test default with specified system label
+    assert_equal Framework.find(:first, :conditions => ["system_name = ?", "RUBY_ON_RAILS"]), Framework.default
+    
+  end
+  
+  
+  def test_method_missing_finders
+    
+    # dynamic find on stand-alone model
+    record = Framework.find_by_system_name("RUBY_ON_RAILS")
+    assert !record.nil?
+    
+    #dynamic find on sti model
+    record = Role.find_by_system_label("SUPERUSER")
+    assert !record.nil?
+    
+  end
+  
+  
+  
+  #---------------------------------------------
+  # test instance methods
+  #---------------------------------------------
+  
+  def test_to_s
+    role = Role.first
+    assert_equal role.label, role.to_s
+  end
+  
+  
+  def test_upcase_system_label_value
+    record = Role.create!({ :system_label => "Customer",  :label => "Client" })
+    assert_equal record.system_label, "CUSTOMER"
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,26 @@
+# require rails stuff
+require "rubygems"
+require "active_record"
+require "active_support"
+require "active_support/test_case"
+require "test/unit"
+
+# require plugin
+require "#{File.dirname(__FILE__)}/../init"
+
+
+
+#----------------------------------------------------------
+# Define global methods
+#----------------------------------------------------------
+
+class ActiveSupport::TestCase
+  
+  # This method allows us to use a convenient notation for testing
+  # model validations.
+  def assert_not_valid(object, msg="Object is valid when it should be invalid")
+    assert(!object.valid?, msg)
+  end
+  alias :assert_invalid :assert_not_valid
+
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification 
+name: acts_as_label
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- John Dugan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-10 00:00:00 -06:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+description: This acts_as extension implements a system label and a friendly label on a class and centralizes the logic for performing validations and accessing items by system label.
+email: jdugan@coroutine.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- .gitignore
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- init.rb
+- lib/acts_as_label.rb
+- test/acts_as_label_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/coroutine/acts_as_label
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Gem version of acts_as_label Rails plugin.
+test_files: 
+- test/acts_as_label_test.rb
+- test/test_helper.rb