blobject 0.2.3 → 0.3.2

data/.gitignore

@@ -1,4 +1,4 @@
 *.gem
 .bundle
-Gemfile.lock
 pkg/*
+TODO

data/.pryrc

@@ -1,5 +1,5 @@
 $:.push File.expand_path('../lib', __FILE__)
-require 'ruby-debug'
+require 'debugger'
 require 'blobject'
 
 def reload!

data/Gemfile.lock

@@ -0,0 +1,42 @@
+PATH
+  remote: .
+  specs:
+    blobject (0.3.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    ansi (1.4.2)
+    builder (3.0.0)
+    coderay (1.0.6)
+    columnize (0.3.6)
+    debugger (1.1.3)
+      columnize (>= 0.3.1)
+      debugger-linecache (~> 1.1.1)
+      debugger-ruby_core_source (~> 1.1.2)
+    debugger-linecache (1.1.1)
+      debugger-ruby_core_source (>= 1.1.1)
+    debugger-ruby_core_source (1.1.3)
+    method_source (0.7.1)
+    minitest (3.0.1)
+    minitest-reporters (0.7.1)
+      ansi
+      builder
+      minitest (>= 2.0, < 4.0)
+      ruby-progressbar
+    pry (0.9.9.6)
+      coderay (~> 1.0.5)
+      method_source (~> 0.7.1)
+      slop (>= 2.4.4, < 3)
+    ruby-progressbar (0.0.10)
+    slop (2.4.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  blobject!
+  debugger
+  minitest
+  minitest-reporters
+  pry

data/README.markdown

@@ -0,0 +1,157 @@
+![](https://github.com/sjltaylor/blobject/raw/master/blobject.png)
+![](https://github.com/sjltaylor/blobject/raw/master/blob_defn.png)
+
+Data structures which __just work__
+
+## About
+
+A Blobject is a thin wrapper around a hash
+
+
+They are *freeform* which means you can do this...
+
+    data = Blobject.new
+
+    data.name   = "Johnny"
+    data.number = 316
+
+like an OpenStruct, the members are not predefined attributes
+
+unlike OpenStruct, Blobjects can be arbitrarily *complex* which means you can do this...
+
+    data = Blobject.new
+
+    data.name.first   = "Johnny"
+    data.name.surname = "Begood"
+
+    data.my.object.with.deep.nested.members = "happy place"
+
+You can test to see if a member is defined:
+
+    data.something_here?
+      => false
+
+
+
+## Used for Configuration
+
+Consider a configuration object which contains credentials for a third-party api.
+
+    third_party_api:
+      secret_key: 'S3CR3T'
+      endpoint: 'http://services.thirdparty.net/api'
+
+With a hash, usage looks like this:
+    
+    CONFIG[:third_party_api][:endpoint]
+
+With a Blobject, usage looks like this:
+
+    CONFIG.third_party_api.endpoint
+
+References to the endpoint are scattered throughout the codebase, then one day the endpoint is separated into its constituent parts to aide in testing and staging.
+
+    third_party_api:
+      secret_key: 'S3CR3T'
+      protocol: 'http'
+      hostname: 'services.thirdparty.net'
+      path: '/api'
+
+Using a blobject we can easily avoid having to refactor our code...
+
+    CONFIG = Blobject.from_yaml(File.read('./config.yml'))
+
+    CONFIG.third_party_api.instance_eval do
+      def endpoint
+        "#{protocol}://#{hostname}#{path}"
+      end
+    end
+
+
+## Serialization
+
+Blobjects can be used to easily build complex payloads.
+
+    person = Blobject.new
+
+    person.name = first: 'David', last: 'Platt'
+    
+    person.address.tap do |address|
+      address.street = "..."
+      address.city   = "..."
+    end
+
+    person.next_of_kin.address.city = '...'
+
+    # after the payload is constructed it can be frozen to prevent modification
+    person.freeze
+
+A nice pattern in most cases is to use an initialization block...
+
+    Blobject.new optional_hash_of_initial_data do |b|
+      b.name = ...
+    end.freeze
+
+
+## Deserialization
+
+
+Suppose you receive a payload from an api which may or may not contain an address and city...
+
+    payload = Blobject.from_json request[:payload]
+
+    # if the payload does have an address...
+    city = payload.address.city
+      => 'Liverpool'
+
+    # if the payload does not have an address or city
+    city = payload.address.city
+      => nil
+    # rather than request[:payload][:address][:city] which would raise
+    # NoMethodError: undefined method `[]' for nil:NilClass
+
+
+Also, you don't need to concern yourself whether hash keys are symbols or strings.
+
+
+
+## Performance
+
+The runtime performance of something as low level as blobject deserves consideration.
+
+see `/benchmarks`
+
+ITERATIONS: 1000000
+
+
+BENCHMARK: assign
+
+            user       system     total       real
+Object:     0.190000   0.000000   0.190000 (  0.229685)
+Hash:       0.220000   0.000000   0.220000 (  0.230500)
+OpenStruct: 0.520000   0.000000   0.520000 (  0.529861)
+Blobject:   0.790000   0.000000   0.790000 (  0.808610)
+Hashie:     8.270000   0.030000   8.300000 (  9.291184)
+
+
+BENCHMARK: read
+
+            user       system     total       real
+Hash:       0.160000   0.000000   0.160000 (  0.165141)
+Object:     0.170000   0.000000   0.170000 (  0.170228)
+OpenStruct: 0.340000   0.000000   0.340000 (  0.342430)
+Blobject:   0.410000   0.000000   0.410000 (  0.410574)
+Hashie:     1.880000   0.000000   1.880000 (  1.921718)
+
+Host CPU: 2.13GHz Core2
+
+A Blobject is three-four times slower than an equivalent Object.
+
+
+## Limitations
+
+* will not work with basic objects unless #class and #freeze are implemented
+* cyclic blobject graphs result in infinite recursion StackOverflow
+* Ruby 1.8.7 is not supported. Testing rubies...
+  * mri 1.9.3-p194
+  * mri 1.9.2-p290

data/Rakefile

@@ -1,2 +1,2 @@
 require 'bundler'
-Bundler::GemHelper.install_tasks
+Bundler::GemHelper.install_tasks

data/benchmarks/benchmark.rb

@@ -0,0 +1,100 @@
+require 'benchmark'
+require 'hashie'
+require 'ostruct'
+require_relative '../lib/blobject'
+
+
+iterations = ARGV[0] || 1000000
+
+
+class A # a foo-bar class the we'll use when benchmarking objects
+  attr_accessor :member1
+end
+
+
+object   = A.new
+blobject = Blobject.new
+hash     = {}
+hashie   = Hashie::Mash.new
+ostruct  = OpenStruct.new
+
+value = "data"
+
+
+
+puts "\n\nITERATIONS: #{iterations}\n\n"
+puts "\nBENCHMARK: assign\n=====================\n\n"
+
+
+
+Benchmark.bm do |benchmark|
+
+  benchmark.report("Object: ") do
+    iterations.times do
+      object.member1 = value
+    end
+  end
+
+  benchmark.report("Hash: ") do
+    iterations.times do
+      hash[:member1] = value
+    end
+  end
+
+  benchmark.report("Blobject: ") do
+    iterations.times do
+      blobject.member1 = value
+    end
+  end
+
+  benchmark.report("Hashie: ") do
+    iterations.times do
+      hashie.member1 = value
+    end
+  end
+
+  benchmark.report("OpenStruct: ") do
+    iterations.times do
+      ostruct.member1 = value
+    end
+  end
+end
+
+
+
+puts "\n\nBENCHMARK: read\n=====================\n\n"
+
+
+
+Benchmark.bm do |benchmark|
+
+  benchmark.report("Object: ") do
+    iterations.times do
+      value = object.member1
+    end
+  end
+
+  benchmark.report("Hash: ") do
+    iterations.times do
+      value = hash[:member1]
+    end
+  end
+
+  benchmark.report("Blobject: ") do
+    iterations.times do
+      value = blobject.member1
+    end
+  end
+
+  benchmark.report("Hashie: ") do
+    iterations.times do
+      value = hashie.member1
+    end
+  end
+
+  benchmark.report("OpenStruct: ") do
+    iterations.times do
+      value = ostruct.member1
+    end
+  end
+end

data/benchmarks/results

@@ -0,0 +1,12 @@
+
+
+ITERATIONS: 1000000
+
+
+BENCHMARK: assign
+=====================
+
+       user     system      total        real
+Object:   0.180000   0.000000   0.180000 (  0.229544)
+Hash:   0.230000   0.000000   0.230000 (  0.241922)
+Hashie: 

data/blobject.gemspec

@@ -14,9 +14,10 @@ Gem::Specification.new do |s|
 
   s.rubyforge_project = "blobject"
   
-  
-  s.add_development_dependency 'rspec'
-  s.add_development_dependency 'ruby-debug19'
+  s.add_development_dependency 'minitest'
+  s.add_development_dependency 'minitest-reporters'
+  s.add_development_dependency 'pry'
+  s.add_development_dependency 'debugger'
   
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")

data/console

@@ -0,0 +1,7 @@
+#! /usr/bin/env ruby
+
+require 'ruby-debug' if ARGV.delete 'debug'
+require './lib/blobject'
+require 'pry'
+
+Pry.start

data/lib/blobject.rb

@@ -1,209 +1,259 @@
-require 'blobject/version'
 require 'json'
-
-def blobject *parameters, &block
-  Blobject.new *parameters, &block
-end
+require 'yaml'
+require_relative 'blobject/version'
 
 class Blobject
   
-  def initialize hash = {}, &block
-    @hash = {}
-    merge hash
-    
-    @modifying = false
-    self.modify &block if block_given?
-  end
-  
-  def modify &block
-    
-    __r_modify_set__ true
-    
-    exception = nil
-    
-    begin
-      self.instance_eval &block
-    rescue Exception => e
-      exception = e
+  # filter :to_ary else Blobject#to_ary returns a
+  # blobject which is not cool, especially if you are puts.
+  ProhibitedNames = [:to_ary]
+
+  module Error; end
+
+  def initialize hash = {}
+
+    @hash = hash
+
+    @hash.keys.each do |key|
+      unless key.class <= Symbol
+        value = @hash.delete key
+        key = key.to_sym
+        @hash[key] = value
+      end
+    end
+
+    __visit_subtree__ do |name, node|
+      if node.class <= Hash
+        @hash[name] = Blobject.new node
+      end
     end
+
+    yield self if block_given?
+  end
+
+  def inspect
     
-    __r_modify_set__ false
+    @hash.inspect
+  end
+
+  def hash
     
-    raise exception unless exception.nil?
-    return self
+    @hash
   end
-  
-  def method_missing sym, *params, &block
+
+  def to_hash
     
-    if match = /^has_(.+)\?/.match(sym)
-      return @hash.has_key? match[1].to_sym
+    h = hash.dup
+    __visit_subtree__ do |name, node|
+      h[name] = node.to_hash if node.respond_to? :to_hash
     end
-    
-    if @modifying
-      
-      case params.length
-      when 0 # get
-        value = @hash[sym] 
-        
-        if value
-          value.modify(&block) if block_given? and value.instance_of?(Blobject)
-          return value
-        end
-        
-        child = Blobject.new
-        parent = self
-        
-        child.__r_modify_set__ true
-        
-        store_in_parent = lambda {
-          
-          parent_hash = parent.instance_variable_get '@hash'
-          parent_hash[sym] = child
-
-          parent_store_in_parent = parent.instance_variable_get :@__store_in_parent__
-          parent_store_in_parent.call unless parent_store_in_parent.nil?
-          
-          child.method(:remove_instance_variable).call(:@__store_in_parent__)
-        }
-        
-        child.instance_variable_set :@__store_in_parent__, store_in_parent
-        
-        return block_given? ? child.modify(&block) : child
-      when 1 # set
-        @hash[sym] = params[0]
-        
-        store_in_parent = @__store_in_parent__
-        store_in_parent.call unless store_in_parent.nil?
-        
-        return self
-      end 
-    else
-      return @hash[sym] if @hash.has_key? sym
+    h
+  end
+
+  # method_missing is only called the first time an attribute is used. successive calls use
+  # memoized getters, setters and checkers
+  def method_missing method, *params, &block
+
+    __tag_and_raise__ NoMethodError.new(method) if ProhibitedNames.include?(method)
+
+    case
+    # assignment in conditionals is usually a bad smell, here it helps minimize regex matching
+    when (name = method[/^\w+$/, 0]) && params.length == 0
+      # the call is an attribute reader
+      return nil if frozen? and not @hash.has_key?(method)
+
+      self.class.send :__define_attribute__, name
+
+      return send(method) if @hash.has_key? method
+
+      parent          = self
+      nested_blobject = self.class.new
+
+      store_in_parent = lambda do
+        parent.send "#{name}=", nested_blobject
+        nested_blobject.send :remove_instance_variable, :@store_in_parent
+      end
+
+      nested_blobject.instance_variable_set :@store_in_parent, store_in_parent
+
+      return nested_blobject
+
+    when (name = method[/^(\w+)=$/, 1]) && params.length == 1
+      # the call is an attribute writer
+
+      self.class.send :__define_attribute__, name
+      return send method, params.first
+
+    when (name = method[/^(\w+)\?$/, 1]) && params.length == 0
+      # the call is an attribute checker
+
+      self.class.send :__define_attribute__, name
+      return send method
     end
-    
+
     super
   end
-  
-  def merge hash
-    
-    hash.each do |key, value|
-      @hash[key.to_s.to_sym] = self.class.__blobjectify__ value
-    end 
+
+  def respond_to? method
     
-    self
-  end
-  
-  def empty?
-    @hash.empty?
+    return true  if self.methods.include?(method)
+    return false if ProhibitedNames.include?(method)
+
+    method = method.to_s
+
+    [/^(\w+)=$/, /^(\w+)\?$/, /^\w+$/].any? do |r|
+      r.match(method)
+    end
   end
-  
-  def [] key
-    @hash[key.to_s.to_sym]
+
+  def == other
+    return @hash == other.hash if other.class <= Blobject
+    return @hash == other      if other.class <= Hash
+    super
   end
-  
-  def keys
-    @hash.keys
+
+  def [] name
+    
+    send name
   end
-  
-  def values
-    @hash.values
+
+  def []= name, value
+    
+    send "#{name.to_s}=", value
   end
   
-  def each &block
-    return @hash.each &block
+  def freeze
+    __visit_subtree__ { |name, node| node.freeze }
+    @hash.freeze
+    super
   end
-  
-  def []= key, value
-    send key, value
+
+  def as_json
+    
+    to_hash
   end
-  
-  def dup
-    Marshal.load(Marshal.dump(self))
+
+  def to_json
+    
+    as_json.to_json
   end
-  
-  def to_hash
-    hash = @hash
+
+  def as_yaml
     
-    hash.each do |key, value|
-      hash[key] = value.to_hash if (value.instance_of? Blobject)
-      
-      if value.instance_of? Array
-        hash[key] = value.map do |v|
-          v.instance_of?(Blobject) ? v.to_hash : v
-        end
-      end
-    end
+    to_hash
+  end
+
+  def to_yaml
     
-    hash
+    as_yaml.to_yaml
   end
-  
-  def from_hash hash
-    Blobject.new hash
+
+  def self.from_json json
+    
+    from_json!(json).freeze
   end
-  
-  def to_yaml *params
-    to_hash.to_yaml *params
+
+  def self.from_json! json
+    
+    __from_hash_or_array__(JSON.parse(json))
   end
-  
+
   def self.from_yaml yaml
-    __blobjectify__ YAML.load(yaml)
-  end
-  
-  def to_json *params
-    @hash.to_json *params
+    
+    from_yaml!(yaml).freeze
   end
-  
-  def self.from_json json
-    __blobjectify__ JSON.load(json)
+
+  def self.from_yaml! yaml
+    
+    __from_hash_or_array__(YAML.load(yaml))
   end
-  
-  def self.read path
-    case File.extname(path).downcase
-    when /\.y(a)?ml$/
-      from_yaml File.read(path)
-    when /\.js(on)?$/
-      from_json File.read(path)
-    else
-      raise "Cannot handle file format of #{path}"
+
+private
+# to avoid naming collisions private method names are prefixed and suffix with double unerscores (__)
+
+  def __visit_subtree__ &block
+    
+    @hash.each do |name, node|
+
+      if node.class <= Array
+        node.flatten.each do |node_node|
+          block.call(nil, node_node, &block)
+        end
+      end
+
+      block.call name, node, &block
     end
   end
-  
-  def dup
-    Blobject.new to_hash
-  end
-  
-  def inspect
-    @hash.inspect
+
+  # errors from this library can be handled with rescue Blobject::Error
+  def __tag_and_raise__ e
+    raise e
+  rescue
+    e.extend Blobject::Error
+    raise e
   end
 
-protected
-  
-  def self.__blobjectify__ obj
-    
-    if obj.instance_of?(Hash)
-      
-      obj.each do |key, value|
-        obj[key] = __blobjectify__ value
+  class << self
+
+  private
+
+    def __from_hash_or_array__ hash_or_array
+
+      if hash_or_array.class <= Array
+        return hash_or_array.map do |e|
+          if e.class <= Hash
+             Blobject.new e
+          else
+            e
+          end
+        end
       end
-      
-      return self.new obj
+
+      Blobject.new hash_or_array
     end
-    
-    if obj.instance_of?(Array)
-      return obj.map do |e|
-        __blobjectify__ e
+
+    def __define_attribute__ name
+
+      __tag_and_raise__ NameError.new("invalid attribute name #{name}") unless name =~ /^\w+$/
+      name = name.to_sym
+
+      methods = self.instance_methods
+
+      setter_name = (name.to_s + '=').to_sym
+      unless methods.include? setter_name
+        self.send :define_method, setter_name do |value|
+          begin
+            value = self.class.new(value) if value.class <= Hash
+            @hash[name] = value
+          rescue  ex
+            __tag_and_raise__(ex)
+          end
+          @store_in_parent.call unless @store_in_parent.nil?
+        end
       end
-    end
-    
-    obj
-  end 
-  
-  def __r_modify_set__ v
-    @modifying = v
-    @hash.values.each do |child|
-      if child.class <= Blobject
-        child.__r_modify_set__ v
+
+      unless methods.include? name
+        self.send :define_method, name do
+
+          value = @hash[name]
+
+          if value.nil? && !frozen?
+            value = self.class.new
+            @hash[name] = value
+          end
+
+          value
+        end
       end
+
+      checker_name = (name.to_s + '?').to_sym
+      unless methods.include? checker_name
+        self.send :define_method, checker_name do
+          @hash.key?(name)
+        end
+      end
+
+      name
     end
   end
 end