candywrapper 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+*.swp
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Steve Jang
+
+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,173 @@
+# Candywrapper
+
+This gem provides simple wrapper around a regular ruby Hash object.
+This wrapper provides the following functionality:
+- DSL for defining arbitrarily deep serializable structure
+- JSON serialization
+
+This gem is useful when you want to serialize/deserialize Ruby
+objects to store or to transmit them over network. This gem was designed
+with the following advantages in mind:
+
+1. You can mix-in the functionality to existing Ruby objects.
+
+2. DSL explicitly defines the protocol payload
+   - Serialization only includes whatever is defined via DSL.
+     All other object states are ignored. This clearly delineates
+     object states that are transient from those that are to be
+     preserved across serialization.
+   - Attributes defined via Candywrapper DSL are called
+     "serializable attributes".
+
+3. Light-weight and fast
+   - Serialization payload is represented by a single hash object
+     (containing nested hashes). There is no other bookkeeping
+     going on other than that.
+   - (De-)Serialization is fast since we just use C-compiled JSON
+     gem of the 1 hash object. We never recursively traverse the
+     nested hash structure, since doing that in Ruby would be
+     50-70 times slower than in C.
+
+4. You can nest candywrappers inside candywrappers.
+   - If you nest candywrapper object 2 and object 3 inside
+     candywrapper object 1, there is still only 1 nested hash
+     object wrapped by object 1. In this case, the hash object
+     used by objects 2 and 3 are nested inside the hash object
+     used by object 1. This means that we only ever pass 1 hash
+     object to json generator during serialization.
+   - What happens to object 2 and object 3 in the above story?
+     Those objects are just wrappers around the nested (sub-)
+     hashes of object 1's hash. All these relationships / references
+     are correctly maintained within the accessor methods.
+
+Given this design, please be aware that:
+
+1. Any object state that you want to save or send should be
+   stored in the wrapped hash object. (see usage)
+
+2. The only types that can be stored as serializable attribute
+   are basic JSON primitives, or other candywrapper objects.
+   (see usage) For example, you cannot store a File object in
+   a candywrapper attribute.
+
+3. We do not support multiple references to the same object, circular or not.
+   If you assign the same complex object across multiple serializable
+   attributes, the behavior is undefined. (depending on how JSON generator
+   implementation behaves)
+
+4. Cloning a candywrapper object (.clone) will perform deep copy.
+   If we don't do this, you could end up with two separate objects
+   sharing the same internal state.
+
+5. All serializable attributes are optional in nature. If you don't set
+   them, they won't be part of the serialized payload.
+
+## Known Issues / Todo
+
+1. We do not provide validation of values being assigned to serializable
+   attributes. The reason for this is to keep things as minimal as possible.
+   If we were to provide validation, we would also have to go through
+   any nested raw hash object to see if they satisfy the structure specified
+   in DSL, which means recursively traversing all the elements of the raw
+   hash during deserialization.
+   
+   The only thing that we check for you is whether something is allowed to
+   be nil or not, as such feature tends to catch a lot of real bugs.
+
+2. Currently, we do not support nested array of candywrappers. For now,
+   arrays must only contain other JSON primitives.
+   When we support this in the future, we will probably require each
+   array explicitly define the element type, and we will not allow mixing
+   of multiple candywrapper types within the same array.
+
+3. Currently, we do not support arbitrary hash containing candywrappers
+   as values. The reason for this is that to support deserializing a
+   candywrapper object from value within an arbitrarily nested hash
+   object requires decorating the raw payload. (e.g. mark a hash object
+   as being payload of a candywrapper class using '_class_name' key)
+
+Related advice here is that you stick to explicitly defining your object
+structure, rather than leaving it up to some run-time interpretation
+(based on existence of a specific key-val). I've tried to support this
+kind of functionality before in a previous job, and it became pretty ugly.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'candywrapper'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install candywrapper
+
+## Usage
+
+Here is a simple example to illustrate how to use Candywrapper.
+
+    require 'candywrapper'
+
+    class Address
+      include Candywrapper
+      serializable_attr :street
+      serializable_attr :city
+      serializable_attr :state
+      serializable_attr :zip
+    end
+
+    class Person
+      include Candywrapper
+      serializable_attr :first_name
+      serializable_attr :middle_name
+      serializable_attr :last_name
+      serializable_attr :home_address, Address
+      serializable_attr :work_address, Address
+      def full_name
+        @full_name = [first_name, middle_name, last_name].compact.join(" ")
+      end
+    end
+
+    a = Address.new
+    a.street = "120 Cherry ST N"
+    a.city = "Seattle"
+    a.state = "WA"
+    a.zip = "98101"
+
+    p = Person.new
+    p.home_address = a
+    p.first_name = "James"
+    p.last_name = "Bond"
+    p.full_name           # => "James Bond"
+
+    json = p.serialize_to_json
+    # => 
+    # {
+    #     "first_name": "James", 
+    #     "last_name": "Bond", 
+    #     "home_address": {
+    #         "street": "120 Cherry ST N", 
+    #         "city": "Seattle", 
+    #         "state": "WA", 
+    #         "zip": "98101"
+    #     }
+    # }
+
+    p2 = Person.deserialize_from_json(json)
+    p2.class              # => Person
+    p2.home_address.class # => Address
+    p2.work_address       # => nil
+    p2.full_name          # => "James Bond"
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,22 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require "rake"
+require "rake/testtask"
+
+namespace :test do
+
+  Rake::TestTask.new(:unit) do |test|
+    test.libs << 'test'
+    test.pattern = '{test/unit/**/*_test.rb}'
+  end
+
+  Rake::TestTask.new(:all) do |test|
+    test.libs << 'test'
+    test.pattern = '{test/**/*_test.rb}'
+  end
+
+end
+
+task :test    => "test:unit"
+task :default => "test"
+

data/candywrapper.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/candywrapper/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Steve Jang"]
+  gem.email         = ["estebanjang@gmail.com"]
+  gem.description   = %q{This gem provides DSL for specifying attributes to be included in serailization.}
+  gem.summary       = %q{Please see README.md file for full description of what this gem does.}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "candywrapper"
+  gem.require_paths = ["lib"]
+  gem.version       = Candywrapper::VERSION
+
+  gem.add_dependency("json")
+end

data/lib/candywrapper.rb

@@ -0,0 +1,136 @@
+require "time"
+require "json"
+require "candywrapper/version"
+
+# === Description
+# Mix-in to add serializable attribute support to a class.
+# Please refer to candywrapper gem README.md documentation.
+#
+module Candywrapper
+
+  CANDYWRAPPER_OBJ = '@candywrapper'.freeze
+
+  def payload_hash
+    @payload_hash ||= {}
+  end
+
+  def payload_hash_set(h)
+    if h.is_a?(Hash)
+      @payload_hash = h
+      h.instance_variable_set(CANDYWRAPPER_OBJ, self)
+    else
+      raise "payload_hash cannot be a non-hash object: #{h.inspect}"
+    end
+  end
+
+  def serialize_to_json
+    JSON.generate(@payload_hash)
+  end
+
+  private
+
+  def candywrapper_object_get(name_s, type, payload_val)
+    obj = payload_val.instance_variable_get(CANDYWRAPPER_OBJ)
+    unless obj
+      obj = type.candywrap_hash(payload_val)
+      payload_val.instance_variable_set(CANDYWRAPPER_OBJ, obj)
+    end
+    obj
+  end
+
+  def candywrapper_object_set(name_s, type, val)
+    if val.is_a?(type)
+      payload_hash[name_s] = val.payload_hash
+    else
+      raise "Expected #{type.inspect} but got #{val.inspect} for #{name_s}"
+    end
+  end
+
+  def candywrapper_attr_get(name_s, type, conversion, opt = {})
+
+    payload_val = payload_hash[name_s]
+    if payload_val.nil?
+      conversion = :none # forgive non-existent attribute in payload
+    end
+
+    case conversion
+    when :none
+      return payload_val
+    when :candywrapper
+      return candywrapper_object_get(name_s, type, payload_val)
+    when :iso8601
+      return Time.parse(payload_val)
+    end
+  end
+
+  def candywrapper_attr_set(name_s, type, conversion, val, opt = {})
+
+    if val.nil?
+      raise "Nil is not allowed for #{name_s} attribute" if opt[:no_nil]
+      conversion = :none
+    end
+
+    case conversion
+    when :none
+      payload_hash[name_s] = val
+    when :candywrapper
+      candywrapper_object_set(name_s, type, val)
+    when :iso8601
+      if val.is_a?(Time)
+        payload_hash[name_s] = val.utc.strftime("%FT%T%z")
+      else
+        raise "Expected #{type.inspect} but got #{val.inspect} for #{name_s}"
+      end
+    end
+  end
+
+  module ClassMethods
+
+    def candywrap_hash(h)
+      obj = self.new
+      obj.payload_hash_set(h)
+      obj
+    end
+
+    def deserialize_from_json(json)
+      h = JSON.parse(json)
+      candywrap_hash(h)
+    end
+
+    # === Description
+    # Add a serializable attribute to the current class.
+    #
+    # === Parameters
+    # name:: (Symbol) Attribute name
+    # type:: (Class)  Class of the attribute value; nil to indicate "don't care"
+    # opt::  (Hash)   Additional options
+    # * opt[:no_nil]:: do not allow nil assignment
+    #
+    def serializable_attr(name, type = nil, opt = {})
+
+      name_s = name.to_s
+      if type.respond_to?(:ancestors) and type.ancestors.include?(Candywrapper)
+        conversion = :candywrapper
+      elsif type == Time
+        conversion = :iso8601
+      else
+        conversion = :none
+      end
+
+      define_method name_s do
+        candywrapper_attr_get(name_s, type, conversion, opt)
+      end
+
+      define_method "#{name_s}=" do |val|
+        candywrapper_attr_set(name_s, type, conversion, val, opt)
+      end
+    end
+    
+  end
+
+  def self.included(c)
+    class << c
+      include ClassMethods
+    end
+  end
+end

data/lib/candywrapper/version.rb

@@ -0,0 +1,3 @@
+module Candywrapper
+  VERSION = "0.0.1"
+end

data/test/unit/basic_test.rb

@@ -0,0 +1,165 @@
+ENV['SERVICE_ROOT'] = File.expand_path(File.dirname(__FILE__))
+require 'minitest/autorun'
+require 'candywrapper'
+
+class Address
+  include Candywrapper
+  serializable_attr :street
+  serializable_attr :city
+  serializable_attr :state
+  serializable_attr :zip
+  serializable_attr :created_at, Time
+end
+
+class Person
+  include Candywrapper
+  serializable_attr :first_name
+  serializable_attr :middle_name
+  serializable_attr :last_name
+  serializable_attr :home_address, Address
+  serializable_attr :work_address, Address
+  serializable_attr :created_at,   Time
+  serializable_attr :database_id,  Integer, :no_nil => true
+  def full_name
+    @full_name = [first_name, middle_name, last_name].compact.join(" ")
+  end
+end
+
+class CandywrapperTest < MiniTest::Unit::TestCase
+
+  def setup
+    @a = Address.new
+    @a.street = "120 Cherry ST N"
+    @a.city = "Seattle"
+    @a.state = "WA"
+    @a.zip = "98101"
+
+    @p = Person.new
+    @p.home_address = @a
+    @p.first_name = "James"
+    @p.last_name = "Bond"
+  end
+
+  def test_accessors
+
+    assert_equal(@p.home_address.class, Address)
+    assert_equal("120 Cherry ST N", @p.home_address.street)
+    assert_equal("Seattle",         @p.home_address.city)
+    assert_equal("WA",              @p.home_address.state)
+    assert_equal("98101",           @p.home_address.zip)
+    assert_equal(nil,               @p.work_address)
+    
+    ah = @p.home_address.payload_hash
+    assert_equal("120 Cherry ST N", ah['street'])
+    assert_equal("Seattle",         ah['city'])
+    assert_equal("WA",              ah['state'])
+    assert_equal("98101",           ah['zip'])
+
+    assert_equal("James",           @p.first_name)
+    assert_equal("Bond",            @p.last_name)
+    assert_equal(nil,               @p.middle_name)
+    assert_equal("James Bond",      @p.full_name)
+
+  end
+
+  def test_time_conversion
+
+    t1 = Time.parse('2012-08-18T06:10:00 MDT')
+    t2 = Time.parse('2012-08-18T06:20:00 MDT')
+    t3 = Time.parse('2012-08-18T05:20:00 PDT')
+    assert_equal(t2, t3)
+
+    @p.created_at = t1
+    @p.home_address.created_at = t2
+
+    assert_equal("2012-08-18T12:10:00+0000", @p.payload_hash['created_at'])
+    assert_equal("2012-08-18T12:20:00+0000", @p.payload_hash['home_address']['created_at'])
+
+    json = @p.serialize_to_json
+
+    p2 = Person.deserialize_from_json(json)
+    assert_equal("2012-08-18T12:10:00+0000", p2.payload_hash['created_at'])
+    assert_equal("2012-08-18T12:20:00+0000", p2.payload_hash['home_address']['created_at'])
+
+    assert_equal(t1, p2.created_at)
+    assert_equal(t2, p2.home_address.created_at)
+    assert_equal(t3, p2.home_address.created_at)
+
+  end
+
+  def test_serialization
+
+    json = @p.serialize_to_json
+
+    h = JSON.parse(json)
+    assert_equal('James',           h['first_name'])
+    assert_equal('Bond',            h['last_name'])
+    assert_equal(nil,               h['middle_name'])
+    assert_equal('120 Cherry ST N', h['home_address']['street'])
+    assert_equal('Seattle',         h['home_address']['city'])
+    assert_equal('WA',              h['home_address']['state'])
+    assert_equal('98101',           h['home_address']['zip'])
+
+  end
+
+  def test_deserialization
+
+    json = @p.serialize_to_json
+
+    p2 = Person.deserialize_from_json(json)
+    assert_equal("James",           p2.first_name)
+    assert_equal(nil,               p2.middle_name)
+    assert_equal("Bond",            p2.last_name)
+    assert_equal(nil,               p2.work_address)
+    assert_equal(nil,               p2.created_at)
+    assert_equal("James Bond",      p2.full_name)
+
+    assert_equal("120 Cherry ST N", p2.home_address.street)
+    assert_equal("Seattle",         p2.home_address.city)
+    assert_equal("WA",              p2.home_address.state)
+    assert_equal("98101",           p2.home_address.zip)
+    assert_equal(nil,               p2.home_address.created_at)
+
+  end
+
+  def test_errors
+
+    begin
+      @p.database_id = nil
+    rescue => e
+      assert(e.to_s =~ /Nil is not allowed/)
+    end
+
+    begin
+      @p.work_address = "100 5th Ave"
+    rescue => e
+      assert(e.to_s =~ /Expected Address but got/)
+    end
+
+    begin
+      @p.created_at = "2012-01-01"
+    rescue => e
+      assert(e.to_s =~ /Expected Time but got/)
+    end
+
+    # Bad type in payload is forgiven, until you try to access it
+    #
+    h = JSON.parse(@p.serialize_to_json)
+    h['work_address'] = "100 5th Ave"
+    json = JSON.generate(h)
+    p2 = Person.deserialize_from_json(json)
+    begin
+      p2.work_address
+    rescue => e
+      assert(e.to_s =~ /payload_hash cannot be a non-hash object/)
+    end
+
+    # No exceptions
+    #
+    p2.work_address = Address.new # we can fix it later
+    p2.work_address.street = "100 5th Ave"
+
+  end
+
+end
+

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: candywrapper
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Steve Jang
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: &11759500 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *11759500
+description: This gem provides DSL for specifying attributes to be included in serailization.
+email:
+- estebanjang@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- candywrapper.gemspec
+- lib/candywrapper.rb
+- lib/candywrapper/version.rb
+- test/unit/basic_test.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: Please see README.md file for full description of what this gem does.
+test_files:
+- test/unit/basic_test.rb