encoder 0.0.1 → 0.0.2

data/README.markdown

@@ -0,0 +1,70 @@
+# Encode
+
+## About
+
+Encode makes it easy use get meaningful descriptions from encoded values.
+
+    task.status = 'P'
+    task.status.decode # => 'Pending'
+    
+It also simplifies using constants to define encoded values and descriptions.
+
+    task.status = Task::Status::New
+    task.status # => 'N'
+    task.status.decode # => 'New'
+
+## Observations
+
+1. Magic numbers and characters make code more difficult to maintain because they don't have instrinsic meaning.
+1. Magic strings, while meaningful, make code more difficult to maintain because minor variations can cause subtle problems.
+1. Literal values scattered throughout a codebase increase refactoring time and effort.
+1. Mapping between encoded values and descriptions shouldn't require a lot of effort.
+
+## Using Encoder
+
+### Setup
+    class Task < ActiveRecord::Base
+      include Encoder
+  
+      code :status do
+        Status::New      = "N"
+        Status::Pending  = "P"
+        Status::Finished = "F"
+        Status::OverDue  = "O"
+      end
+  
+      code :priority do
+        Priority::High =  1
+        Priority::Low =   5
+      end
+  
+    end
+
+### Usage Examples
+    t = Task.new # => #<Task id: nil, status: nil, priority: nil>
+
+    # Using a constant to assign the value
+    t.status = Task::Status::New # => "N"
+    t.status # => "N"
+    t.status.decode # => "New"
+
+    # Using a decoded value to assign the value
+    t.priority = 1 # => 1
+    t.priority # => 1
+    t.priority.decode # => "High"
+
+    # Obtaining a list of the constant names defined for each attribute
+    Task::Status.constants # => ["Pending", "New", "OverDue", "Finished"]
+    Task::Priority.constants # => ["Low", "High"]
+    Task::Priority.values # => [5, 1]
+    Task::Priority.mapping # => { "Low" => 5, "High" => 1 }
+    
+
+## To Do
+
+- Auto-mixin on init
+- Choose a better name
+- Use shoulda or rspec
+- Obtain list of constant values (for use with validations)
+
+Copyright (c) 2010 Jon Morton, released under the MIT license

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.2

data/lib/encoder.rb

@@ -1,3 +1,9 @@
+# Adding decode to all objects simplifies the complexity of handling
+# Fixnums with decodable values.
+class Object
+  attr_accessor :decode
+end
+
 module Encoder
   
   def self.included(base)
@@ -29,11 +35,25 @@ module Encoder
     def code(attribute_name, &block)
       
       # Create a 'namespace' for constants 
-      const_set(attribute_name.to_s.camelcase, Module.new)
+      namespace = const_set(attribute_name.to_s.camelcase, Module.new)
       
       # Expecting constants to be assigned values.
       yield
       
+      # Add methods for obtaining namespaced constants and their values.
+      namespace.module_eval do
+        def self.values
+          constants.map { |c| self.const_get(c) }
+        end
+        def self.mapping
+          constants.inject(Hash.new) do |memo, const|
+            memo[const] = self.const_get(const)
+            memo
+          end
+        end
+      end
+      
+      
       # create setter for attribute
       self.send(:define_method, "#{attribute_name}=") do |arg|
         
@@ -47,14 +67,14 @@ module Encoder
         # Since the given value might not match the constant name exactly
         # (because of case sensitivity or white space variations) we
         # normalize it a bit.
-        normalized = arg && arg.gsub(/\s+/,'').downcase
+        normalized = arg && arg.to_s.gsub(/\s+/,'').downcase
         
         # Now we look for a constant whose name or actual value match the
         # normalized argument.  We 'tap' whatever constant name is found
         # and lookup the actual value.
         namespace.constants.find do |const_name|
-          normalized == const_name.downcase ||
-          normalized == namespace.const_get(const_name).downcase
+          normalized == const_name.to_s.downcase ||
+          normalized == namespace.const_get(const_name).to_s.downcase
         end.tap do |match|
           encoded_value = namespace.const_get(match) if match
         end
@@ -74,12 +94,12 @@ module Encoder
           namespace.const_get(constant) == encoded_attribute
         end.first
       
-        encoded_attribute.instance_variable_set(:@decoding, decoded_value)
-      
-        class << encoded_attribute
-          def decode
-            @decoding && @decoding.underscore.titleize
-          end
+        if decoded_value.is_a?(Fixnum)
+          encoded_attribute.instance_variable_set(:@decode, decoded_value)
+        elsif ! decoded_value.nil?
+          encoded_attribute.instance_variable_set(:@decode, decoded_value.underscore.titleize)
+        else
+          encoded_attribute.instance_variable_set(:@decode, nil)
         end
       
         return encoded_attribute

data/test/database.rb

@@ -29,8 +29,8 @@ class Task < ActiveRecord::Base
 	end
 	
 	code :priority do
-	  Priority::High =  "H"
-	  Priority::Low =   "L"
+	  Priority::High = 1
+	  Priority::Low  = 5
   end
 	
 end

data/test/functional/encoder_test.rb

@@ -21,4 +21,14 @@ class EncoderTest < ActiveSupport::TestCase
     assert db_task.status.decode == 'New'
   end
   
+  test "setting an attribute using mass assignment should encode a decoded value" do
+    task = ::Task.new({ :status => 'New' })
+    assert task.status == 'N'
+  end
+  
+  test "setting an attribute using mass assignment should ignore a value" do
+    task = ::Task.new({ :status => 'Nothing Matches This' })
+    assert task.status == nil
+  end
+  
 end

data/test/unit/encoder_test.rb

@@ -66,4 +66,25 @@ class EncoderTest < ActiveSupport::TestCase
     assert Task.const_defined?(:FooBar)
   end
   
+  test "constants with fixnum values" do
+    t = ::Task.new
+    t.priority = 1
+    assert t.priority == Task::Priority::High
+  end
+
+  test "namespaced constants" do
+    assert Task::Priority.constants.all? { |v| ["High", "Low"].include?(v) }
+  end
+  
+  test "namespaced values" do
+    assert Task::Priority.values.all? { |v| [1,5].include?(v) }
+  end
+  
+  test "namespaced mapping" do
+    assert Task::Priority.mapping == {
+      "High" => 1,
+      "Low" => 5
+    }
+  end
+  
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: encoder
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - Jon Morton
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-20 00:00:00 -04:00
+date: 2010-04-06 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
@@ -20,11 +20,11 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
-- README
+- README.markdown
 files: 
 - .gitignore
 - MIT-LICENSE
-- README
+- README.markdown
 - Rakefile
 - VERSION
 - install.rb

data/README

@@ -1,44 +0,0 @@
-Encode
-=========
-
-Encode makes it easy to go from codes to meaningful strings.
-
-Example
-=======
-
-Suppose you have a task in one of three possible states: pending, active, finished.  When you store tasks, you'd like to have the state represented as P for pending, A for active, and F, for finished.  However, you don't want to worry about the details of turning a state into a specific character.
-
-t = Task.new('feed the cat')
-
-# By default 
-t.status = Status::Pending
-t.status         # => 'P'
-t.status.decode  # => 'Pending'
-
-# You'd probably encapsulate this in a method though wouldn't you?
-t.finish!
-
-# How should that be implemented though?
-@status = 'f'
-@status = 'finished'
-@status = Task::Status::Finished
-
-However, you want to store the state as a single character behind the scenes without having to define a bunch of custom getters or setters. 
-
-class Task
-	code :status do
-	  Status::Pending = "P" 
-	  Status::Active = "A"
-	  Status::Finished = "F"
-	end
-end
-
-To Do
-=====
-
-[ ] Auto-mixin on init
-[ ] Make a proper gem
-[ ] Choose a better name
-[ ] Use shoulda or rspec (maybe)
-
-Copyright (c) 2010 Jon Morton, released under the MIT license