ostruct2 0.1.0 → 0.2.0

data/.ruby

@@ -52,7 +52,7 @@ revision: 0
 created: '2010-04-21'
 summary: A Better OpenStruct
 title: OStruct2
-version: 0.1.0
+version: 0.2.0
 name: ostruct2
 description: ! 'OStruct2 is a reimplementation of Ruby''s standard ostruct.rb library.
 
@@ -60,4 +60,4 @@ description: ! 'OStruct2 is a reimplementation of Ruby''s standard ostruct.rb li
 
   member names and cloning.'
 organization: Rubyworks
-date: '2012-05-20'
+date: '2012-05-23'

data/HISTORY.rdoc

@@ -1,8 +1,24 @@
 = RELEASE HISTORY
 
-0.1.0 | 2011-01-01
+== 0.2.0 | 2012-05-23
 
-Summary of release...
+This release brings the new OpenStruct to a production ready state.
+
+Changes:
+
+* Constructors cascade and auto/renew are now slightly different.
+* Added nest/nested constructor for nests OpenStructs. (Cool!)
+* Boost performace via on-demand creation of singleton methods.
+* Add missing equality methods, hash method and dup/clone methods.
+* Rename main class to OpenStruct2 to avoid conflicts with original.
+* Require `ostruct2/ostruct` to get drop-in replacement.
+
+
+== 0.1.0 | 2011-05-20
+
+This is the initial relase of OpenSturct2.
+
+Changes:
 
 * First release.
 

data/lib/ostruct2/ostruct.rb

@@ -0,0 +1,7 @@
+require 'ostruct2'
+
+class OpenStruct < OpenStruct2
+  def __class__
+    OpenStruct
+  end
+end

data/lib/ostruct2.rb

@@ -1,29 +1,122 @@
-# A better OpenStruct class.
+# OpenStruct2 is a better OpenStruct class.
 #
-class OpenStruct < BasicObject
+# To demonstrate the weakness of the original OpenStruct, try this IRB session:
+#
+#   irb(main):001:0> o = OpenStruct.new
+#   => #<OpenStruct>
+#   irb(main):002:0> o.display = "Hello, World!"
+#   => "Hello, World!"
+#   irb(main):003:0> o.display
+#   #<OpenStruct display="Hello, World!">=> nil
+#
+# This new OpenStruct class allows *almost* any member name to be used.
+# The only exceptions are methods starting with double underscores,
+# such as `__id__` and `__send__`, and a few neccessary public
+# methods: `clone`, `dup`, `freeze`, `hash`, `to_enum`, `to_h`,
+# `to_s` and `inspect`, as well as `instance_eval` and `instance_exec`.
+#
+# Also note that `empty`, `eql`, `equal`, `frozen` and `key` can be used as
+# members but the key-check shorthand of using `?`-methods cannot be used since
+# these have special definitions.
+#
+# To offset the loss of most methods, OpenStruct provides numerous
+# bang-methods which can be used to manipulate the data, e.g. `#each!`.
+# Currently most bang-methods route directly to the underlying hash table,
+# so developers should keep that in mind when using this feature. A future
+# version may add an intermediate interface to always ensure proper "CRUD",
+# functonality but in the vast majority of cases it will make no difference,
+# so it is left for later consideration.
+#
+# This improved version of OpenStruct also has no issues with being cloned
+# since it does not depend on singleton methods to work. But singleton methods
+# are used to help boost performance. But instead of always creating singleton
+# methods, it only creates them on the first attempt to use them.
+#
+class OpenStruct2 < BasicObject
 
   class << self
     #
-    # Create cascading OpenStruct.
+    # Create autovivified OpenStruct.
     #
-    def cascade(data=nil)
-      leet = lambda{ |h,k| OpenStruct.new(&leet) }
+    # @example
+    #   o = OpenStruct2.renew
+    #   o.a  #=> #<OpenStruct2: {}>
+    #
+    def auto(data=nil)
+      leet = lambda{ |h,k| new(&leet) }
       new(&leet)
     end
 
-    # Is there a better name for #auto?
-    #alias :autorenew :cascade
+    #
+    # Another name for #auto method.
+    #
+    # TODO: Still wondering waht the best name is for this.
+    #
+    alias :renew :auto
+
+    #
+    # Create a nested OpenStruct, such that all sub-hashes
+    # added to the table also become OpenStruct objects.
+    #
+    def nested(data=nil)
+      o = new
+      o.nested!(true)
+      o.update!(data) if data
+      o
+    end
+
+    #
+    # Shorter name for `nested`.
+    #
+    alias :nest :nested
+
+    #
+    # Constructor that is both autovivified and nested.
+    #
+    def cascade(data=nil)
+      o = renew
+      o.nested!(true)
+      o.update!(data) if data
+      o
+    end
+
+  private
 
-    # Original name for #cascade method.
-    alias :auto :cascade
+    def const_missing(name)
+      ::Object.const_get(name)
+    end
   end
 
+  #
+  # Initialize new instance of OpenStruct.
+  #
+  # @param [Hash] data
   #
   def initialize(data=nil, &block)
     @table = ::Hash.new(&block)
     update!(data || {})
   end
 
+  #
+  # Because there is no means of getting the class via a BasicObject instance,
+  # we define such a method manually.
+  #
+  def __class__
+    OpenStruct2
+  end
+
+  #
+  # Duplicate underlying table when OpenStruct is duplicated or cloned.
+  #
+  # @param [OpenStruct] original
+  #
+  def initialize_copy(original)
+    super
+    @table = @table.dup
+  end
+
+  #
+  # Dispatch unrecognized member calls.
   #
   def method_missing(sym, *args, &blk)
     str  = sym.to_s
@@ -31,42 +124,84 @@ class OpenStruct < BasicObject
     name = str.chomp('=').chomp('!').chomp('?')
 
     case type
-    when '='
-      store!(name, args.first)
     when '!'
+      # TODO: Probably should have an indirect interface to ensure proper
+      #       functonality in all cases.
       @table.public_send(name, *args, &blk)
+    when '='
+      new_ostruct_member(name)
+      store!(name, args.first)
     when '?'
+      new_ostruct_member(name)
       key?(name)
     else
+      new_ostruct_member(name)
       read!(name)
     end
   end
 
+  #
+  # Get/set nested flag.
+  #
+  def nested!(boolean=nil)
+    if boolean.nil?
+      @nested
+    else
+      @nested = !!boolean
+    end
+  end
+
+  #
   # CRUD method for listing all keys.
+  #
   def keys!
     @table.keys
   end
 
+  #
   # Also a CRUD method like #read!, but for checking for the existence of a key.
+  #
   def key?(key)
     @table.key?(key.to_sym)
   end
 
+  #
   # The CRUD method for read.
+  #
   def read!(key)
     @table[key.to_sym]
   end
 
+  #
   # The CRUD method for create and update.
+  #
   def store!(key, value)
+    if @nested && Hash === value  # value.respond_to?(:to_hash)
+      value = OpenStruct2.new(value)
+    end
+
+    #new_ostruct_member(key)  # this is here only for speed bump
+
     @table[key.to_sym] = value
   end
 
+  #
   # The CRUD method for destroy.
+  #
   def delete!(key)
     @table.delete(key.to_sym)
   end
 
+  #
+  # Same as `#delete!`. This method provides compatibility
+  # with the original OpenStruct class.
+  #
+  # @deprecated Use `#delete!` method instead.
+  #
+  def delete_field(key)
+    @table.delete(key.to_sym)
+  end
+
   #
   # Like #read but will raise a KeyError if key is not found.
   #
@@ -75,37 +210,83 @@ class OpenStruct < BasicObject
     read!(key)
   end
 
+  #
+  # If key is not present raise a KeyError.
+  #
+  # @param [#to_sym] key
+  #
+  # @raise [KeyError] If key is not present.
+  #
+  # @return key
+  #
+  def key!(key)
+    return key if key?(key)
+    ::Kernel.raise ::KeyError, ("key not found: %s" % [key.inspect])
+  end
+
+  #
+  # Alias for `#read!`.
+  #
+  # @param [#to_sym] key
+  #
+  # @return [Object]
   #
   def [](key)
     read!(key)
   end
 
+  #
+  # Alias for `#store!`.
+  #
+  # @param [#to_sym] key
+  #
+  # @param [Object] value
+  #
+  # @return value.
   #
   def []=(key, value)
     store!(key, value)
   end
 
+  #
   # CRUDified each.
+  #
+  # @return nothing
+  #
   def each!
     @table.each_key do |key|
       yield(key, read!(key))
     end
   end
 
+  #
+  def map!(&block)
+    to_enum.map(&block)
+  end
+
+  #
   # CRUDified update method.
+  #
+  # @return [self]
+  #
   def update!(other)
     other.each do |k,v|
       store!(k,v)
     end
+    self
   end
 
+  #
+  # Merge this OpenStruct with another OpenStruct or Hash object
+  # returning a new OpenStruct instance.
   #
   # IMPORTANT! This method does not act in-place like `Hash#merge!`,
   # rather it works like `Hash#merge`.
   #
+  # @return [OpenStruct]
+  #
   def merge!(other)
-    # TODO: is there anyway to #dup a BasicObject subclass instance?
-    o = ::OpenStruct.new(@table, &@table.default_proc)
+    o = dup
     other.each do |k,v|
       o.store!(k,v)
     end
@@ -113,38 +294,114 @@ class OpenStruct < BasicObject
   end
 
   #
-  # Is the OpenStruct void of entries?
+  # Inspect OpenStruct object.
   #
-  def empty?
-    @table.empty?
+  # @return [String]
+  #
+  def inspect
+    "#<#{__class__}: #{@table.inspect}>"
   end
 
+  alias :to_s :inspect
+
   #
   # Get a duplicate of the underlying table.
   #
+  # @return [Hash]
+  #
   def to_h
     @table.dup
   end
 
+  # TODO: Should OpenStruct2 support #to_hash ?
+  #alias :to_hash :to_h
+
+  #
+  # Create an enumerator based on `#each!`.
+  #
+  # @return [Enumerator]
   #
   def to_enum
     ::Enumerator.new(self, :each!)
   end
 
   #
-  # If key is not present raise a KeyError.
+  # Duplicate OpenStruct object.
   #
-  def key!(key)
-    return key if key?(key)
-    ::Kernel.raise ::KeyError, ("key not found: %s" % [key.inspect])
+  # @return [OpenStruct] Duplicate instance.
+  #
+  def dup
+    __class__.new(@table, &@table.default_proc)
   end
 
+  alias :clone :dup
+
   #
+  # Hash number.
   #
+  def hash
+    @table.hash
+  end
+
   #
-  def inspect
-    "#<OpenStruct: #{@table.inspect}>"
+  # Freeze OpenStruct instance.
+  #
+  def freeze
+    @table.freeze
   end
 
-end
+  #
+  # Is the OpenStruct instance frozen?
+  #
+  # @return [Boolean]
+  #
+  def frozen?
+    @table.frozen?
+  end
 
+  #
+  # Is the OpenStruct void of entries?
+  #
+  def empty?
+    @table.empty?
+  end
+
+  #
+  # Two OpenStructs are equal if they are the same class and their
+  # underlying tables are equal.
+  #
+  def eql?(other)
+    return false unless(other.kind_of?(__class__))
+    return @table == other.table #to_h
+  end
+
+  #
+  # Two OpenStructs are equal if they are the same class and their
+  # underlying tables are equal.
+  #
+  # TODO: Why not equal for other hash types, e.g. via #to_h?
+  #
+  def ==(other)
+    return false unless(other.kind_of?(__class__))
+    return @table == other.table #to_h
+  end
+
+protected
+
+  def table
+    @table
+  end
+
+  def new_ostruct_member(name)
+    name = name.to_sym
+    # TODO: Check `#respond_to?` is needed? And if so how to do this in BasicObject?
+    #return name if self.respond_to?(name)
+    (class << self; self; end).class_eval do
+      define_method(name) { read!(name) }
+      define_method("#{name}?") { key?(name) }
+      define_method("#{name}=") { |value| store!(name, value) }
+    end
+    name
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ostruct2
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-20 00:00:00.000000000 Z
+date: 2012-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: detroit
-  requirement: &26950880 !ruby/object:Gem::Requirement
+  requirement: &22522480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *26950880
+  version_requirements: *22522480
 - !ruby/object:Gem::Dependency
   name: qed
-  requirement: &26950340 !ruby/object:Gem::Requirement
+  requirement: &22521760 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *26950340
+  version_requirements: *22521760
 - !ruby/object:Gem::Dependency
   name: ae
-  requirement: &26949840 !ruby/object:Gem::Requirement
+  requirement: &22521140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *26949840
+  version_requirements: *22521140
 description: ! 'OStruct2 is a reimplementation of Ruby''s standard ostruct.rb library.
 
   This new OpenStruct class addresses issues the original has with conflicting
@@ -55,16 +55,17 @@ executables: []
 extensions: []
 extra_rdoc_files:
 - HISTORY.rdoc
-- DEMO.rdoc
 - README.rdoc
+- DEMO.md
 files:
 - .ruby
+- lib/ostruct2/ostruct.rb
 - lib/ostruct2.rb
 - HISTORY.rdoc
-- DEMO.rdoc
 - README.rdoc
+- DEMO.md
 - Config.rb
-homepage: 
+homepage: http://rubyworks.github.com/ostruct2
 licenses:
 - BSD-2-Clause
 post_install_message: