decor 0.1.0

data/Gemfile

@@ -0,0 +1,7 @@
+source "http://rubygems.org"
+
+group :development do
+  gem "bundler", "~> 1.0.0"
+  gem "rake", "~> 0.8.7"
+  gem "rspec", "2.1.0"
+end

data/Gemfile.lock

@@ -0,0 +1,21 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    rake (0.8.7)
+    rspec (2.1.0)
+      rspec-core (~> 2.1.0)
+      rspec-expectations (~> 2.1.0)
+      rspec-mocks (~> 2.1.0)
+    rspec-core (2.1.0)
+    rspec-expectations (2.1.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  rake (~> 0.8.7)
+  rspec (= 2.1.0)

data/Rakefile

@@ -0,0 +1,17 @@
+require "rubygems"
+require "bundler"
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = ["-c", "-f progress", "-r ./spec/spec_helper.rb"]
+  t.pattern = 'spec/**/*_spec.rb'
+end
+
+task :default => :spec

data/Readme.textile

@@ -0,0 +1,159 @@
+h1. Decor
+
+Define multiple representations of an object.
+
+"Read the documentation":http://empl.us/decor/ or see an example scenario and usage below.
+
+h2. Scenario
+
+You have an API. It returns provides access to a User resource. This resource:
+
+<pre>
+create_table do |t|
+  t.string :screen_name
+  t.string :state,  :default => "active"
+  t.string :role,   :default => "user"
+end
+
+class User < ActiveRecord::Base
+  STATES  = ["active", "inactive"]
+  ROLES   = ["user", "admin"]
+end
+</pre>
+
+At one point, you had just defined booleans for @active@ and @admin@, but you have plans to expand the states and roles of a User. However, you already provide an API that you do not wish to break.
+
+How do you transition your code and your data over and not break backwards compatibility? How do you do this modularly and in an easily testable way without making your API endpoints (controllers et al) heavy?
+
+How about:
+
+<pre>
+class User < ActiveRecord::Base
+  include Decor
+  
+  STATES  = ["active", "inactive"]
+  ROLES   = ["user", "admin"]
+  
+  version "v1" do
+    def active
+      state == "active"
+    end
+    def admin
+      role == "admin"
+    end
+    
+    def as_json(options = {})
+      super(options.merge(:only => [:screen_name],
+                          :methods => [:active, :admin]))
+    end
+  end
+  
+  version "v2" do
+    def as_json(*args)
+      super(options.merge(:only => [:screen_name, :state, :role]))
+    end
+  end
+  
+end
+</pre>
+
+Then, our endpoint:
+
+<pre>
+get '/api/:version/users/:id' do
+  @user = User.find(params[:id])
+  @user.for(version).to_json
+end
+</pre>
+
+You can also include external resources providing some contextual influence over how your resources choose to represent themselves:
+
+<pre>
+class User < ActiveRecord::Base
+  include Decor
+  
+  version "v3" do
+    def screen_name
+      "%s (%s)" % [super, organization.name]
+    end
+  end
+  
+end
+
+get '/api/:version/organizations/:org_id/users/:id' do
+  @organization = Organization.find(params[:org_id])
+  @user = User.find(params[:id]).for(version, :organization => @organization)
+  @user.to_json
+end
+</pre>
+
+h2. Example Usage
+
+Defining your class and versions:
+
+<pre>
+class Resource < Struct.new(:name, :value)
+  include Decor
+  
+  version "v1" do
+    # a computed value specific to this version
+    def computed
+      value * 10
+    end
+  end
+  
+  version "v2" do
+    # overloaded name
+    def name
+      super.reverse
+    end
+    
+    # different computed value for this version
+    def computed
+      value * 100
+    end
+  end
+  
+  def unversioned
+    "yes"
+  end
+end
+</pre>
+
+Using the versioned instance:
+
+<pre>
+resource = resource.for(version)
+</pre>
+
+h2. Contributing
+
+Feel free to open "Issues":https://github.com/mtodd/decor/issues or fork and create "Pull Requests":https://github.com/mtodd/decor/pulls.
+
+The minimum for contribution is a failing spec. If you can at least convey what the problem is or the feature you'd like to add in a failing spec, I will be much more motivated to fix the issue or add the feature.
+
+If you'd like to fix the bug or implement the feature yourself, feel free to! Please document and test your code thoroughly and in similar fashion to what already exists.
+
+h2. Copyright and License
+
+The MIT License
+
+Copyright (c) 2010 Matt Todd.
+
+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/decor.gemspec

@@ -0,0 +1,52 @@
+Gem::Specification.new do |s|
+  s.name = %q{decor}
+  s.version = "0.1.0"
+  
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Matt Todd"]
+  s.date = %q{2010-12-13}
+  s.description = %q{Provides a simple way to define multiple representations of an object}
+  s.email = %q{chiology@gmail.com}
+  s.files = [
+    "decor.gemspec",
+    "Gemfile",
+    "Gemfile.lock",
+    "Rakefile",
+    "Readme.textile",
+    "lib/decor.rb",
+    "spec/decor_spec.rb",
+    "spec/models/bare.rb",
+    "spec/models/resource.rb",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://empl.us/decor/}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Defines multiple representations of objects}
+  s.test_files = [
+    "spec/spec_helper.rb",
+    "spec/decor_spec.rb",
+    "spec/models/bare.rb",
+    "spec/models/resource.rb"
+  ]
+  
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+    
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency("bundler", ["~> 1.0.0"])
+      s.add_development_dependency("rake",    ["~> 0.8.7"])
+      s.add_development_dependency("rspec",   ["= 2.1.0"])
+    else
+      s.add_dependency("bundler", ["~> 1.0.0"])
+      s.add_dependency("rake",    ["~> 0.8.7"])
+      s.add_dependency("rspec",   ["= 2.1.0"])
+    end
+  else
+    s.add_dependency("bundler", ["~> 1.0.0"])
+    s.add_dependency("rake", ["~> 0.8.7"])
+    s.add_dependency("rspec", ["= 2.1.0"])
+  end
+end

data/lib/decor.rb

@@ -0,0 +1,317 @@
+# Decor provides a simple way to define multiple representations of an object.
+# 
+# This is useful for when you want to retain multiple versions of your objects
+# while providing a consistent interface between versions.
+# 
+# For example:
+# 
+#     class Company < ActiveRecord::Base
+#       include Decor
+#       
+#       # the first version, customers are dependent on certain artifacts
+#       # like industry_id and industry
+#       version "v1" do
+#         INDUSTRIES = {1 => "Farm",
+#                       2 => "Software"}
+#         
+#         def industry
+#           INDUSTRIES[industry_id]
+#         end
+#         
+#         def as_json(*_)
+#           super(:only     => [:id, :name, :industry_id],
+#                 :methods  => [:industry])
+#         end
+#       end
+#       
+#       # switch to using industry standard codes, cleans up the name
+#       version "v2" do
+#         SIC_CODES = {...}
+#         
+#         # use the cleaned name for the name instead
+#         def name
+#           name_cleaned
+#         end
+#         
+#         def industry
+#           SIC_DOES[sic_code]
+#         end
+#         
+#         def as_json(*_)
+#           super(:only     => [:id, :name, :sic_code],
+#                 :methods  => [:industry])
+#         end
+#       end
+#       
+#     end
+# 
+# In our API, for instance, we can then define a single endpoint for both
+# versions:
+# 
+#     get "/api/:version/companies/:id.json" do
+#       Company.find(params[:id]).for(version).to_json
+#     end
+# 
+# This helps us keep our models fat and our "controllers" skinny. This also
+# helps unit testing the versions of your API.
+# 
+# Further details can be found on [Github](https://github.com/mtodd/decor/).
+# 
+module Decor
+  
+  # Decor is a mixin. Include it into your class and then use the `version`
+  # class methods in the class body to define your versions, then use the
+  # `for` instance method on your objects to use a specific version.
+  # 
+  # For example:
+  # 
+  #     class Model
+  #       include Decor
+  #       
+  #       version "v1" do
+  #         # implement specifics for this version here
+  #       end
+  #     end
+  # 
+  #     model = Model.new.for("v1")
+  # 
+  def self.included(target)
+    target.send(:extend, ClassMethods)
+    class << target; attr_accessor :versions; end
+    target.versions = {}
+  end
+  
+  module ClassMethods
+    # Defines versions of the model's representation.
+    # 
+    # The `version` supplied is a string representation of the version.
+    # For example, `"v1"` represents version 1 of this model's representation.
+    # 
+    # The `version` is just a key, however, and any value works. Strings are
+    # convenient, especially in the form of `v1` or `v2010-12-09`.
+    # 
+    # If a block is provided, the block is treated as the body of the version's
+    # definition.
+    # 
+    # If a hash of `version => version_module` is passed in, we use your module
+    # instead of creating our own.
+    # 
+    # For example:
+    # 
+    #     class Model
+    #       include Decor
+    #       
+    #       version "v1" do
+    #         # ...
+    #       end
+    # 
+    #       module V20101209
+    #         # ...
+    #       end
+    #       version "v2010-12-09" => V20101209
+    #       
+    #       # or use classes (for example) as version keys and alias to other
+    #       # versions
+    #       version AnotherModel  => "v1"
+    #       version OtherModel    => V20101209
+    #       
+    #     end
+    # 
+    def version(version, &block)
+      case
+      # Look up version module if no version block or module specified.
+      #     version "v1" #=> #<Module>
+      when self.versions.key?(version)
+        return self.versions[version]
+        
+      # Define a new version from the block.
+      #     version "v1" { ... }
+      when block_given?
+        constant = Module.new(&block)
+        self.versions[version] = constant
+        self
+        
+      # Set versions from a module, supports as many versions as passed in.
+      #     version "v1"        => Version1,
+      #             "v2"        => Version2,
+      #             "v20101209" => "v2" # supports aliases
+      else
+        version.each do |(new_version, module_or_version)|
+          self.versions[new_version] =
+          if module_or_version.is_a?(Module)
+            module_or_version
+          else
+            self.versions[module_or_version]
+          end
+        end
+        
+      end
+      self
+    end
+  end
+  
+  # An object will be told to behave like the version specified.
+  # 
+  # Options provide additional values in the context of the verions.
+  # 
+  #     class Model
+  #       include Decor
+  #       
+  #       version "v1" do
+  #         def versioned?
+  #           true
+  #         end
+  #       end
+  #       
+  #       def versioned?
+  #         false
+  #       end
+  #     end
+  # 
+  #     model = Model.new
+  #     model.          versioned?  #=> false
+  #     model.for("v1").versioned?  #=> true
+  # 
+  # An optional context can be supplied which will make external resources
+  # available for specific functions in your versions. For example:
+  # 
+  #     class User
+  #       include Decor
+  #       
+  #       version "v1" do
+  #         def display_name
+  #           "%s (%s)" % [name, band.display_name]
+  #         end
+  #       end
+  #     end
+  # 
+  #     user = User.find(id).for("v1", :band => external_band)
+  #     user.display_name #=> "Dan Auerbach (The Black Keys)"
+  # 
+  # Lastly, it's possible to pass in a `:module` option which will override the
+  # module already defined for the version specified (making the `version`
+  # passed in almost meaningless).
+  # 
+  #     module Specialized
+  #       # special considerations here
+  #     end
+  #     
+  #     Model.new.for("v1", :module => Specialized)
+  # 
+  def for(version, options = {})
+    version_module = self.version_module_for(version, options)
+    decorator = Class.new(Base).new(self, version, options)
+    decorator.send(:extend, version_module)
+    decorator
+  end
+  
+  # Handles finding the module defined for the `version` specified, or
+  # overriding with the `:module` option.
+  # 
+  # See `for` for details.
+  # 
+  def version_module_for(version, options = {})
+    return options.delete(:module)      if options.key?(:module)
+    return self.class.versions[version] if self.class.versions.key?(version)
+    self.class.const_get(version.upcase)
+  end
+  
+  # The basis of our version wrapper.
+  # 
+  # Whenever a version is specified using `Decor#for`, it is wrapped in a
+  # decoration that makes it behave like the specified version.
+  # 
+  # This decoration proxies all calls it doesn't define itself to the original
+  # object (the `target`).
+  # 
+  # `options` provides context, which are treated as instance methods for the
+  # versions. See `for` for details.
+  # 
+  class Base < Struct.new(:target, :version, :options)
+    
+    # This proxies calls to the target if we don't define it explicitly.
+    # 
+    # However, if the `options` context defines a key that matches the `method`
+    # name, we return that value instead.
+    # 
+    def method_missing(method, *args, &block)
+      return options[method]                    if options.key?(method)
+      return target.send(method, *args, &block) if respond_to?(method)
+      super
+    end
+    
+    # We can handle the method call if we have a match in the `options` context
+    # or if our `target` object responds to the method.
+    # 
+    # For example:
+    # 
+    #     class Model
+    #       include Decor
+    #       
+    #       version "v1" do
+    #         def foo
+    #         end
+    #       end
+    #       
+    #       def baz
+    #       end
+    #       
+    #     end
+    # 
+    #     model = Model.new.for("v1", :bar => true)
+    #     model.respond_to?(:foo)   #=> true # in version
+    #     model.respond_to?(:bar)   #=> true # in context
+    #     model.respond_to?(:baz)   #=> true # on target
+    #     model.respond_to?(:quux)  #=> false
+    # 
+    def respond_to?(method)
+      super or options.key?(method) or target.respond_to?(method)
+    end
+    
+    # If `for` is called on an object that is already wrapped by a version,
+    # we return the `target` with a new version wrapper. This allows for an
+    # object to change its version representation at will.
+    # 
+    # For example:
+    # 
+    #     class Model
+    #       include Decor
+    #       
+    #       version "v1" do
+    #         def original?
+    #           true
+    #         end
+    #       end
+    #       
+    #       version "v2" do
+    #         def original?
+    #           false
+    #         end
+    #       end
+    #     end
+    # 
+    #     model = Model.new.for("v1")
+    #     model.original? #=> true
+    #     
+    #     model = model.for("v2")
+    #     model.original? #=> false
+    # 
+    def for(*args)
+      target.for(*args)
+    end
+    
+    # This provides additional context to the versions specified. Useful for
+    # making external resources accessible, overriding accessors, etc.
+    # 
+    # Ensures `options` is an empty Hash even when not set.
+    # 
+    def options
+      super or begin
+        self.options = {}
+        redo
+      end
+    end
+    
+  end
+  
+end

data/spec/decor_spec.rb

@@ -0,0 +1,139 @@
+require 'spec_helper'
+
+require 'models/bare'
+require 'models/resource'
+
+describe Decor do
+  
+  describe "when included in a class" do
+    
+    describe ".version" do
+      it "should be available" do
+        Bare.should_not respond_to(:version)
+        Bare.send(:include, Decor)
+        Bare.should respond_to(:version)
+      end
+      
+      it "should define a collection of versions" do
+        Bare.versions.should respond_to(:to_hash)
+      end
+      
+      it "should allow new versions to be defined with a block" do
+        Bare.should respond_to(:version)
+        Bare.version("v1"){}
+        Bare.versions.key?("v1").should be_true
+      end
+      
+      it "should allow new versions to be defined with a module" do
+        v2 = Module.new
+        Bare.version "v2" => v2
+        Bare.versions.key?("v2").should be_true
+        Bare.versions["v2"].should == v2
+      end
+      
+      it "should return versions by name when no block or module is given" do
+        v3 = Module.new
+        Bare.version "v3" => v3
+        Bare.version("v3").should == v3
+      end
+      
+      it "should turn a block into a module" do
+        Bare.version("v4"){}
+        Bare.version("v4").should be_a(Module)
+      end
+    end
+    
+    describe "#for" do
+      subject{ Bare.new }
+      
+      it "should decorate the object with the version specified" do
+        subject.for("v1").version.should == "v1"
+      end
+      
+      it "should target the instance" do
+        subject.for("v1").target.should be_a(Bare)
+        subject.for("v1").target.should == subject
+      end
+      
+      it "should decorate with an instance of Decor::Base" do
+        subject.for("v1").should be_a(Decor::Base)
+      end
+      
+      it "should decorate by including the version module" do
+        subject.for("v1").should be_a(Bare.version("v1"))
+      end
+      
+    end
+    
+  end
+  
+  describe Decor::Base do
+    before{ @version = "v1"; @name = "foo"; @value = 2; @multi = 2; @options = {} }
+    subject{ Resource.new(@name, @value, @multi).for(@version, @options) }
+    
+    it "should delegate to the object" do
+      subject.name.should == @name
+    end
+    
+    it "should allow version switching" do
+      resource = subject
+      resource.version.should == "v1"
+      resource = resource.for("v2")
+      resource.version.should == "v2"
+      resource.name.should == @name.upcase
+    end
+    
+    it "should allow overriding the module for the version" do
+      v2 = Module.new
+      resource = subject.for("v1", :module => v2)
+      resource.should be_a(v2)
+    end
+    
+    describe "v1" do
+      before{ @version = "v1" }
+      
+      it "should delegate to the target for original values" do
+        subject.name.should == @name
+      end
+      
+      it "should allow computed values" do
+        subject.computed.should == @value * @multi
+      end
+    end
+    
+    describe "v2" do
+      before{ @version = "v2" }
+      
+      it "should allow modified versions of methods in the target" do
+        subject.name.should == @name.upcase
+      end
+      
+      it "should allow constants in the context of the version" do
+        subject.computed.should == @value * @multi * Resource::Version2::MUTLI
+      end
+      
+    end
+    
+    describe "v2010-12-08" do
+      before{ @version = "v2010-12-08" }
+      
+      it "should keep the name of the alias as the version" do
+        subject.version.should == "v2010-12-08"
+      end
+      
+      it "should be the same as its alias" do
+        subject.should be_a(subject.target.class.version("v2"))
+      end
+    end
+    
+    describe "v3" do
+      before{ @version = "v3"; @options = {:foo => "bar"} }
+      
+      it "should use values in the context hash as methods" do
+        subject.name.should == "%s (%s)" % [@name, @options[:foo]]
+      end
+    end
+    
+  end
+  
+end

data/spec/models/bare.rb

@@ -0,0 +1,2 @@
+class Bare
+end

data/spec/models/resource.rb

@@ -0,0 +1,37 @@
+class Resource < Struct.new(:name, :value, :multi)
+  include Decor
+  
+  # Module method
+  module V1
+    def computed
+      value * multi
+    end
+  end
+  version "v1" => V1
+  
+  # Module method, non-standard
+  module Version2
+    MUTLI = 10
+    def name
+      super.upcase
+    end
+    def computed
+      value * multi * MUTLI
+    end
+  end
+  # mutliple aliases
+  version "v2"          => Version2,
+          "v2010-12-08" => Version2
+  
+  # Block method
+  version "v3" do
+    # utilizes options hash
+    def name
+      "%s (%s)" % [super, foo]
+    end
+    def computed
+      nil
+    end
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+$:.unshift(File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib')))
+require 'rubygems'
+require 'bundler/setup'
+require 'decor'
+
+require 'rspec'

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification 
+name: decor
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Matt Todd
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-12-13 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 49
+        segments: 
+        - 0
+        - 8
+        - 7
+        version: 0.8.7
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        hash: 11
+        segments: 
+        - 2
+        - 1
+        - 0
+        version: 2.1.0
+  type: :development
+  version_requirements: *id003
+description: Provides a simple way to define multiple representations of an object
+email: chiology@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- decor.gemspec
+- Gemfile
+- Gemfile.lock
+- Rakefile
+- Readme.textile
+- lib/decor.rb
+- spec/decor_spec.rb
+- spec/models/bare.rb
+- spec/models/resource.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://empl.us/decor/
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Defines multiple representations of objects
+test_files: 
+- spec/spec_helper.rb
+- spec/decor_spec.rb
+- spec/models/bare.rb
+- spec/models/resource.rb