hashery 1.5.0 → 2.0.0

data/lib/hashery/open_cascade.rb

@@ -1,99 +1,154 @@
 require 'hashery/open_hash'
-#require 'facets/nullclass'
 
-# = OpenCascade
-#
-# OpenCascade is subclass of OpenHash. It differs in a few
-# significant ways.
-#
-# The main reason this class is labeled "cascade", every internal
-# Hash is transformed into an OpenCascade dynamically upon access.
-# This makes it easy to create "cascading" references.
-#
-#   h = { :x => { :y => { :z => 1 } } }
-#   c = OpenCascade[h]
-#   c.x.y.z  #=> 1
-#
-# As soon as you access a node it automatically becomes an OpenCascade.
-#
-#   c = OpenCascade.new   #=> #<OpenCascade:0x7fac3680ccf0 {}>
-#   c.r                   #=> #<OpenCascade:0x7fac368084c0 {}>
-#   c.a.b                 #=> #<OpenCascade:0x7fac3680a4f0 {}>
-#
-# But if you set a node, then that will be it's value.
-#
-#   c.a.b = 4             #=> 4
-#
-# To query a node without causing the auto-creation of an OpenCasade
-# object, use the ?-mark.
-#
-#   c.a.z?                #=> nil
-#
-# OpenCascade also transforms Hashes within Arrays.
-#
-#  h = { :x=>[ {:a=>1}, {:a=>2} ], :y=>1 }
-#  c = OpenCascade[h]
-#  c.x.first.a.assert == 1
-#  c.x.last.a.assert == 2
-#
-# Finally, you can set a node and get the reciever back using
-# the !-mark.
-#
-#   c = OpenCascade.new   #=> #<OpenCascade:0x7fac3680ccf0 {}>
-#   c.x!(4).y!(3)         #=> #<OpenCascade:0x7fac3680ccf0 {:x=>4, :y=>3}>
-#
-#--
-# Last, when an entry is not found, 'null' is returned rather then 'nil'.
-# This allows for run-on entries withuot error. Eg.
-#
-#   o = OpenCascade.new
-#   o.a.b.c  #=> null
-#
-# Unfortuately this requires an explict test for null? in 'if' conditions.
-#
-#   if o.a.b.c.null?  # true if null
-#   if o.a.b.c.nil?   # true if nil or null
-#   if o.a.b.c.not?   # true if nil or null or false
-#
-# So be sure to take that into account.
-#++
-
-class OpenCascade < OpenHash
+module Hashery
 
+  # OpenCascade is subclass of OpenHash. It differs in a few
+  # significant ways. The reason this class is called "cascade" is that
+  # every internal Hash is transformed into an OpenCascade dynamically
+  # upon access. This makes it easy to create "cascading" references.
+  #
+  #   h = { :x => { :y => { :z => 1 } } }
+  #   c = OpenCascade[h]
+  #   c.x.y.z  #=> 1
+  #
+  # As soon as you access a node it automatically becomes an OpenCascade.
+  #
+  #   c = OpenCascade.new   #=> #<OpenCascade:0x7fac3680ccf0 {}>
+  #   c.r                   #=> #<OpenCascade:0x7fac368084c0 {}>
+  #   c.a.b                 #=> #<OpenCascade:0x7fac3680a4f0 {}>
   #
-  def method_missing(sym, *args, &blk)
-    type = sym.to_s[-1,1]
-    name = sym.to_s.gsub(/[=!?]$/, '').to_sym
-    case type
-    when '='
-      self[name] = args.first
-    when '!'
-      #@hash.__send__(name, *args, &blk)
-      __send__(name, *args, &blk)
-    when '?'
-      self[name]
-    else
-      if key?(name)
-        self[name] = transform_entry(self[name])
+  # But if you set a node, then that will be that value.
+  #
+  #   c.a.b = 4             #=> 4
+  #
+  # To query a node without causing the auto-creation of an OpenCasade
+  # instance, use the `?`-mark.
+  #
+  #   c.a.z?                #=> nil
+  #
+  # OpenCascade also transforms Hashes within Arrays.
+  #
+  #   h = { :x=>[ {:a=>1}, {:a=>2} ], :y=>1 }
+  #   c = OpenCascade[h]
+  #   c.x.first.a.assert == 1
+  #   c.x.last.a.assert  == 2
+  #
+  # Finally, you can set call a private method via bang methods using the `!`-mark.
+  #
+  #   c = OpenCascade.new   #=> #<OpenCascade:0x7fac3680ccf0 {}>
+  #   c.each = 4
+  #   c.each! do |k,v|
+  #     ...
+  #   end
+  #
+  #   c.x!(4).y!(3)         #=> #<OpenCascade:0x7fac3680ccf0 {:x=>4, :y=>3}>
+  #
+  class OpenCascade < OpenHash
+
+    #
+    #def self.[](hash)
+    #  oc = new
+    #  hash.each{ |(k,v)| oc.store(k,v) }
+    #  oc
+    #end
+
+    #
+    # Initialize new OpenCascade instance.
+    #
+    # default - The usual default object.
+    #
+    def initialize(*default)
+      @read = {}
+
+      leet = lambda { |h,k| h[k] = OpenCascade.new(&leet) }
+      super(*default, &leet)
+    end
+
+    #
+    # Alias for original read method.
+    #
+    alias :read! :read
+
+    #
+    # Read value given a +key+.
+    #
+    # key - Index keey to lookup.
+    #
+    # Returns value.
+    #
+    def read(key)
+      if @read[cast_key(key)]
+        super(key)
       else
-        self[name] = OpenCascade.new #self.class.new
+        @read[cast_key(key)] = store(key, cast_value(super(key)))
       end
     end
-  end
+
+    #
+    #
+    #
+    def method_missing(sym, *args, &blk)
+      type = sym.to_s[-1,1]
+      name = sym.to_s.gsub(/[=!?]$/, '').to_sym
+
+      case type
+      when '='
+        store(name, args.first)
+      when '?'
+        key?(name) ? read!(name) : nil    # key?(name)
+      when '!'
+        __send__(name, *args, &blk)
+      else
+        #if key?(name)
+          read(name)
+        #else
+        #  #default = OpenCascade.new #self.class.new
+        #  #default = default_proc ? default_proc.call(self, name) : default
+        #  store(name, read(name))
+        #end
+      end
+    end
+
+    #def each
+    #  super do |key, entry|
+    #    yield([key, transform_entry(entry)])
+    #  end
+    #end
 
   private
 
     #
-    def transform_entry(entry)
+    # Cast value, such that Hashes are converted to OpenCascades.
+    # And Hashes in Arrays are converted to OpenCascades as well.
+    #
+    def cast_value(entry)
       case entry
       when Hash
-        OpenCascade.new(entry) #self.class.new(val)
+        OpenCascade[entry] #self.class.new(val)
       when Array
-        entry.map{ |e| transform_entry(e) }
+        entry.map{ |e| cast_value(e) }
       else
         entry
       end
     end
 
+  end
+
 end
 
+#--
+# Last, when an entry is not found, 'null' is returned rather then 'nil'.
+# This allows for run-on entries withuot error. Eg.
+#
+#   o = OpenCascade.new
+#   o.a.b.c  #=> null
+#
+# Unfortuately this requires an explict test for null? in 'if' conditions.
+#
+#   if o.a.b.c.null?  # true if null
+#   if o.a.b.c.nil?   # true if nil or null
+#   if o.a.b.c.not?   # true if nil or null or false
+#
+# So be sure to take that into account.
+#++
+

data/lib/hashery/open_hash.rb

@@ -1,77 +1,143 @@
-# = OpenHash
-#
-# OpenHash is very similar to Ruby's own OpenStruct, but it offers some
-# useful advantages in that it is a true Hash object.
-#
-# Because OpenHash is a subclass of Hash, it can do everything a Hash
-# can *unless* a Hash method has been explicity exempted for use
-# as an open read/writer via the #omit! method.
+require 'hashery/crud_hash'
 
-class OpenHash < Hash
-
-  # New OpenHash.
-  def initialize(data={})
-    super()
-    merge!(data)
-  end
+module Hashery
 
+  # OpenHash is a Hash, but also supports open properties much like
+  # OpenStruct.
   #
-  def <<(x)
-    case x
-    when Hash
-      update(x)
-    when Array
-      x.each_slice(2) do |(k,v)|
-        self[k] = v
-      end
+  # Only names that are name methods of Hash can be used as open slots.
+  # To open a slot for a name that would otherwise be a method, the 
+  # method needs to be made private. The `#open!` method can be used
+  # to handle this.
+  #
+  # Examples
+  #
+  #     o = OpenHash.new
+  #     o.open!(:send)
+  #     o.send = 4
+  #
+  class OpenHash < CRUDHash
+
+    alias :object_class :class
+
+    #FILTER  = /(^__|^\W|^instance_|^object_|^to_)/
+    #methods = Hash.instance_methods(true).select{ |m| m !~ FILTER }
+    #methods = methods - [:each, :inspect, :send]  # :class, :as]
+    #private *methods
+
+    #
+    # Initialize new OpenHash instance.
+    #
+    # TODO: Maybe `safe` should be the first argument?
+    #
+    def initialize(default=nil, safe=false, &block)
+      @safe = safe
+      super(*[default].compact, &block)
     end
-  end
 
-  #
-  def respond_to?(name)
-    key?(name.to_sym) || super(name)
-  end
+    #
+    # If safe is set to true, then public methods cannot be overriden
+    # by hash keys.
+    #
+    attr_accessor :safe
 
-  #
-  def to_h
-    dup
-  end
+    #
+    # Index `value` to `key`. Unless safe mode, will also open up the 
+    # key if it is not already open.
+    #
+    # key   - Index key to associate with value.
+    # value - Value to be associate with key.
+    #
+    # Returns +value+.
+    #
+    def store(key, value)
+      open!(key)
+      super(key, value)
+    end
 
-  #
-  def to_hash
-    dup
-  end
+    #
+    # Open up a slot that that would normally be a Hash method.
+    #
+    # The only methods that can't be opened are ones starting with `__`.
+    #
+    # methods - [Array<String,Symbol>] method names
+    #
+    # Returns Array of slot names that were opened.
+    #
+    def open!(*methods)
+      # only select string and symbols, any other type of key is allowed,
+      # it just won't be accessible via dynamic methods.
+      methods = methods.select{ |x| String === x || Symbol === x }
+      # @todo should we just ignore these instead of raising an error?
+      #methods.reject!{ |x| x.to_s =~ /^__/ }
+      if methods.any?{ |m| m.to_s.start_with?('__') }
+        raise ArgumentError, "cannot set shadow methods"
+      end
+      # only public methods need to be made private
+      methods = methods.map{ |x| x.to_sym }
+      methods = methods & public_methods(true)
+      if @safe
+        raise ArgumentError, "cannot set public method" unless methods.empty?
+      else
+        (class << self; self; end).class_eval{ private *methods }
+      end
+      methods
+    end
 
-  #
-  def inspect
-    super
-  end
+    # @deprecated
+    alias :omit! :open!
 
-  # Omit specific Hash methods from slot protection.
-  def omit!(*methods)
-    methods.reject!{ |x| x.to_s =~ /^__/ }
-    (class << self; self; end).class_eval{ private *methods }
-  end
+    #
+    # Is a slot open?
+    #
+    # method - [String,Symbol] method name
+    #
+    # Returns `true` or `false`.
+    #
+    def open?(method)
+      ! public_methods(true).include?(method.to_sym)
+    end
 
-  # Route get and set calls.
-  def method_missing(s,*a, &b)
-    type = s.to_s[-1,1]
-    name = s.to_s.sub(/[!?=]$/, '')
-    key  = name.to_sym
-    case type
-    when '='
-      self[key] = a[0]
-    #when '!'
-    #  self[s] = OpenHash.new
-    when '?'
-      key?(key)
-    else
-      if key?(key)
-        self[key]
+    #
+    # Make specific Hash methods available for use that have previously opened.
+    #
+    # methods - [Array<String,Symbol>] method names
+    #
+    # Returns +methods+.
+    #
+    def close!(*methods)
+      (class << self; self; end).class_eval{ public *methods }
+      methods
+    end
+
+    #
+    #
+    #
+    def method_missing(s,*a, &b)
+      type = s.to_s[-1,1]
+      name = s.to_s.sub(/[!?=]$/, '')
+      key  = name.to_sym
+
+      case type
+      when '='
+        #open!(key) unless open?(key)
+        #self[key] = a.first
+        store(key, a.first)
+      when '?'
+        key?(key)
+      when '!'
+        # call an underlying private method
+        # TODO: limit this to omitted methods (from included) ?
+        __send__(name, *a, &b)
       else
-        super(s,*a,&b)
+        #if key?(key)
+          read(key)
+        #else
+        #  super(s,*a,&b)
+        #end
       end
     end
+
   end
 
 end

data/lib/hashery/ordered_hash.rb

@@ -1,163 +1,169 @@
-# = OrderedHash
-#
-# A simple ordered hash implmentation, for users of
-# Ruby 1.8.7 or less.
-#
-# NOTE: As of Ruby 1.9+ this class is not needed, since
-# Ruby 1.9's standard Hash tracks inseration order.
-#
-# This implementation derives from the same class in
-# ActiveSupport library.
-
-class OrderedHash < ::Hash
-
-  def to_yaml_type
-    "!tag:yaml.org,2002:omap"
-  end
-
-  def to_yaml(opts = {})
-    YAML.quick_emit(self, opts) do |out|
-      out.seq(taguri, to_yaml_style) do |seq|
-        each do |k, v|
-          seq.add(k => v)
+module Hashery
+
+  # OrderedHash is a simple ordered hash implmentation, for users of
+  # Ruby 1.8.7 or less.
+  #
+  # NOTE: As of Ruby 1.9+ this class is not needed, since
+  # Ruby 1.9's standard Hash tracks inseration order.
+  #
+  # This implementation derives from the same class in
+  # ActiveSupport library.
+  #
+  class OrderedHash < ::Hash
+
+    def to_yaml_type
+      "!tag:yaml.org,2002:omap"
+    end
+
+    def to_yaml(opts = {})
+      YAML.quick_emit(self, opts) do |out|
+        out.seq(taguri, to_yaml_style) do |seq|
+          each do |k, v|
+            seq.add(k => v)
+          end
         end
       end
     end
-  end
 
-  # Hash is ordered in Ruby 1.9!
-  if RUBY_VERSION < '1.9'
-    def initialize(*args, &block)
-      super
-      @keys = []
-    end
+    # Hash is ordered in Ruby 1.9!
+    if RUBY_VERSION < '1.9'
+
+      def initialize(*args, &block)
+        super
+        @keys = []
+      end
+
+      def self.[](*args)
+        ordered_hash = new
 
-    def self.[](*args)
-      ordered_hash = new
+        if (args.length == 1 && args.first.is_a?(Array))
+          args.first.each do |key_value_pair|
+            next unless (key_value_pair.is_a?(Array))
+            ordered_hash[key_value_pair[0]] = key_value_pair[1]
+          end
 
-      if (args.length == 1 && args.first.is_a?(Array))
-        args.first.each do |key_value_pair|
-          next unless (key_value_pair.is_a?(Array))
-          ordered_hash[key_value_pair[0]] = key_value_pair[1]
+          return ordered_hash
         end
 
-        return ordered_hash
-      end
+        unless (args.size % 2 == 0)
+          raise ArgumentError.new("odd number of arguments for Hash")
+        end
 
-      unless (args.size % 2 == 0)
-        raise ArgumentError.new("odd number of arguments for Hash")
-      end
+        args.each_with_index do |val, ind|
+          next if (ind % 2 != 0)
+          ordered_hash[val] = args[ind + 1]
+        end
 
-      args.each_with_index do |val, ind|
-        next if (ind % 2 != 0)
-        ordered_hash[val] = args[ind + 1]
+        ordered_hash
       end
 
-      ordered_hash
-    end
-
-    def initialize_copy(other)
-      super(other)
-      @keys = other.keys
-    end
+      def initialize_copy(other)
+        super(other)
+        @keys = other.keys
+      end
 
-    def []=(key, value)
-      @keys << key unless key?(key)
-      super(key, value)
-    end
+      def []=(key, value)
+        @keys << key unless key?(key)
+        super(key, value)
+      end
 
-    def delete(key)
-      if has_key? key
-        index = @keys.index(key)
-        @keys.delete_at(index)
+      def delete(key)
+        if has_key? key
+          index = @keys.index(key)
+          @keys.delete_at(index)
+        end
+        super(key)
       end
-      super(key)
-    end
 
-    def delete_if
-      super
-      sync_keys!
-      self
-    end
+      def delete_if
+        super
+        sync_keys!
+        self
+      end
 
-    def reject!
-      super
-      sync_keys!
-      self
-    end
+      def reject!
+        super
+        sync_keys!
+        self
+      end
 
-    def reject(&block)
-      dup.reject!(&block)
-    end
+      def reject(&block)
+        dup.reject!(&block)
+      end
 
-    def keys
-      @keys.dup
-    end
+      def keys
+        @keys.dup
+      end
 
-    def values
-      @keys.collect{ |key| self[key] }
-    end
+      def values
+        @keys.collect{ |key| self[key] }
+      end
 
-    def to_hash
-      self
-    end
+      def to_hash
+        self
+      end
 
-    def to_a
-      @keys.map{ |key| [ key, self[key] ] }
-    end
+      def to_a
+        @keys.map{ |key| [ key, self[key] ] }
+      end
 
-    def each_key
-      @keys.each{ |key| yield(key) }
-    end
+      def each_key
+        @keys.each{ |key| yield(key) }
+      end
 
-    def each_value
-      @keys.each{ |key| yield(self[key]) }
-    end
+      def each_value
+        @keys.each{ |key| yield(self[key]) }
+      end
 
-    def each
-      @keys.each{ |key| yield(key, self[key]) }
-    end
+      def each
+        @keys.each{ |key| yield(key, self[key]) }
+      end
 
-    alias_method :each_pair, :each
+      alias_method :each_pair, :each
 
-    def clear
-      super
-      @keys.clear
-      self
-    end
+      def clear
+        super
+        @keys.clear
+        self
+      end
 
-    def shift
-      k = @keys.first
-      v = delete(k)
-      [k, v]
-    end
+      def shift
+        k = @keys.first
+        v = delete(k)
+        [k, v]
+      end
 
-    def merge!(other_hash)
-      other_hash.each{ |k,v| self[k] = v }
-      self
-    end
+      def merge!(other_hash)
+        other_hash.each{ |k,v| self[k] = v }
+        self
+      end
 
-    def merge(other_hash)
-      dup.merge!(other_hash)
-    end
+      def merge(other_hash)
+        dup.merge!(other_hash)
+      end
 
-    # When replacing with another hash, the initial order of our
-    # keys must come from the other hash, ordered or not.
-    def replace(other)
-      super
-      @keys = other.keys
-      self
-    end
+      # When replacing with another hash, the initial order of our
+      # keys must come from the other hash, ordered or not.
+      def replace(other)
+        super
+        @keys = other.keys
+        self
+      end
 
-    def inspect
-      "#<OrderedHash #{super}>"
-    end
+      def inspect
+        "#<OrderedHash #{super}>"
+      end
 
     private
+
       def sync_keys!
         @keys.delete_if{ |k| !key?(k) }
       end
+
+    end
+
   end
+
 end
 
 require 'yaml'