hashie-pre 2.0.0.beta

data/lib/hashie/extensions/method_access.rb

@@ -0,0 +1,124 @@
+module Hashie
+  module Extensions
+    # MethodReader allows you to access keys of the hash
+    # via method calls. This gives you an OStruct like way
+    # to access your hash's keys. It will recognize keys
+    # either as strings or symbols.
+    #
+    # Note that while nil keys will be returned as nil, 
+    # undefined keys will raise NoMethodErrors. Also note that 
+    # #respond_to? has been patched to appropriately recognize
+    # key methods.
+    #
+    # @example
+    #   class User < Hash
+    #     include Hashie::Extensions::MethodReader
+    #   end
+    #
+    #   user = User.new
+    #   user['first_name'] = 'Michael'
+    #   user.first_name # => 'Michael'
+    #   
+    #   user[:last_name] = 'Bleigh'
+    #   user.last_name # => 'Bleigh'    
+    #
+    #   user[:birthday] = nil
+    #   user.birthday # => nil
+    #
+    #   user.not_declared # => NoMethodError
+    module MethodReader
+      def respond_to?(name)
+        return true if key?(name.to_s) || key?(name.to_sym)
+        super
+      end
+      
+      def method_missing(name, *args)
+        return self[name.to_s] if key?(name.to_s)
+        return self[name.to_sym] if key?(name.to_sym)
+        super
+      end
+    end
+
+    # MethodWriter gives you #key_name= shortcuts for
+    # writing to your hash. Keys are written as strings,
+    # override #convert_key if you would like to have symbols
+    # or something else.
+    #
+    # Note that MethodWriter also overrides #respond_to such
+    # that any #method_name= will respond appropriately as true.
+    #
+    # @example
+    #   class MyHash < Hash
+    #     include Hashie::Extensions::MethodWriter
+    #   end
+    #
+    #   h = MyHash.new
+    #   h.awesome = 'sauce'
+    #   h['awesome'] # => 'sauce'
+    #
+    module MethodWriter
+      def respond_to?(name)
+        return true if name.to_s =~ /=$/
+        super
+      end
+
+      def method_missing(name, *args)
+        if args.size == 1 && name.to_s =~ /(.*)=$/
+          return self[convert_key($1)] = args.first
+        end
+
+        super
+      end
+
+      def convert_key(key)
+        key.to_s
+      end
+    end
+
+    # MethodQuery gives you the ability to check for the truthiness
+    # of a key via method calls. Note that it will return false if
+    # the key is set to a non-truthful value, not if the key isn't
+    # set at all. Use #key? for checking if a key has been set.
+    #
+    # MethodQuery will check against both string and symbol names
+    # of the method for existing keys. It also patches #respond_to
+    # to appropriately detect the query methods.
+    #
+    # @example
+    #   class MyHash < Hash
+    #     include Hashie::Extensions::MethodQuery
+    #   end
+    #
+    #   h = MyHash.new
+    #   h['abc'] = 123
+    #   h.abc? # => true
+    #   h['def'] = nil
+    #   h.def? # => false
+    #   h.hji? # => NoMethodError
+    module MethodQuery
+      def respond_to?(name)
+        return true if name.to_s =~ /(.*)\?$/ && (key?($1) || key?($1.to_sym))
+        super
+      end
+
+      def method_missing(name, *args)
+        if args.empty? && name.to_s =~ /(.*)\?$/ && (key?($1) || key?($1.to_sym))
+          return self[$1] || self[$1.to_sym]
+        end
+
+        super
+      end
+    end
+
+    # A macro module that will automatically include MethodReader,
+    # MethodWriter, and MethodQuery, giving you the ability to read,
+    # write, and query keys in a hash using method call shortcuts.
+    module MethodAccess
+      def self.included(base)
+        [MethodReader, MethodWriter, MethodQuery].each do |mod|
+          base.send :include, mod
+        end
+      end
+    end
+  end
+end

data/lib/hashie/extensions/structure.rb

@@ -0,0 +1,47 @@
+module Hashie
+  module Extensions
+    # The Structure extension provides facilities for declaring
+    # properties that a Hash can have. This provides for the
+    # creation of structures that still behave like hashes but
+    # do not allow setting non-allowed keys.
+    #
+    # @example
+    #   class RestrictedHash < Hash
+    #     include Hashie::Extensions::MergeInitializer
+    #     include Hashie::Extensions::Structure
+    #
+    #     key :first
+    #     key :second, :default => 'foo'
+    #   end
+    #
+    #   h = RestrictedHash.new(:first => 1)
+    #   h[:first]  # => 1
+    #   h[:second] # => 'foo'
+    #   h[:third]  # => ArgumentError
+    #
+    module Structure
+      def self.included(base)
+        base.extend ClassMethods
+        base.class_eval do
+          @permitted_keys = superclass.permitted_keys if superclass.respond_to?(:permitted_keys)
+        end
+      end
+
+      module ClassMethods
+        def key(key, options = {})
+          (@permitted_keys ||= []) << key
+
+          if options[:default]
+            (@default_values ||= {})[key] = options.delete(:default)
+          end
+
+          permitted_keys
+        end
+
+        def permitted_keys
+          @permitted_keys
+        end
+      end
+    end
+  end
+end

data/lib/hashie/hash.rb

@@ -0,0 +1,31 @@
+require 'hashie/hash_extensions'
+
+module Hashie
+  # A Hashie Hash is simply a Hash that has convenience
+  # functions baked in such as stringify_keys that may
+  # not be available in all libraries.
+  class Hash < ::Hash
+    include Hashie::HashExtensions
+
+    # Converts a mash back to a hash (with stringified keys)
+    def to_hash
+      out = {}
+      keys.each do |k|
+        if self[k].is_a?(Array)
+          out[k] ||= []
+          self[k].each do |array_object|
+            out[k] << (Hashie::Hash === array_object ? array_object.to_hash : array_object)
+          end
+        else
+          out[k] = Hashie::Hash === self[k] ? self[k].to_hash : self[k]
+        end
+      end
+      out
+    end
+
+    # The C geneartor for the json gem doesn't like mashies
+    def to_json(*args)
+      to_hash.to_json(*args)
+    end
+  end
+end

data/lib/hashie/hash_extensions.rb

@@ -0,0 +1,49 @@
+module Hashie
+  module HashExtensions
+    def self.included(base)
+      # Don't tread on existing extensions of Hash by
+      # adding methods that are likely to exist.
+      %w(stringify_keys stringify_keys!).each do |hashie_method|
+        base.send :alias_method, hashie_method, "hashie_#{hashie_method}" unless base.instance_methods.include?(hashie_method)
+      end
+    end
+
+    # Destructively convert all of the keys of a Hash
+    # to their string representations.
+    def hashie_stringify_keys!
+      self.keys.each do |k|
+        unless String === k
+          self[k.to_s] = self.delete(k)
+        end
+      end
+      self
+    end
+
+    # Convert all of the keys of a Hash
+    # to their string representations.
+    def hashie_stringify_keys
+      self.dup.stringify_keys!
+    end
+
+    # Convert this hash into a Mash
+    def to_mash
+      ::Hashie::Mash.new(self)
+    end
+  end
+
+  module PrettyInspect
+    def self.included(base)
+      base.send :alias_method, :hash_inspect, :inspect
+      base.send :alias_method, :inspect, :hashie_inspect
+    end
+
+    def hashie_inspect
+      ret = "#<#{self.class.to_s}"
+      stringify_keys.keys.sort.each do |key|
+        ret << " #{key}=#{self[key].inspect}"
+      end
+      ret << ">"
+      ret
+    end
+  end
+end

data/lib/hashie/mash.rb

@@ -0,0 +1,216 @@
+require 'hashie/hash'
+
+module Hashie
+  # Mash allows you to create pseudo-objects that have method-like
+  # accessors for hash keys. This is useful for such implementations
+  # as an API-accessing library that wants to fake robust objects
+  # without the overhead of actually doing so. Think of it as OpenStruct
+  # with some additional goodies.
+  #
+  # A Mash will look at the methods you pass it and perform operations
+  # based on the following rules:
+  #
+  # * No punctuation: Returns the value of the hash for that key, or nil if none exists.
+  # * Assignment (<tt>=</tt>): Sets the attribute of the given method name.
+  # * Existence (<tt>?</tt>): Returns true or false depending on whether that key has been set.
+  # * Bang (<tt>!</tt>): Forces the existence of this key, used for deep Mashes. Think of it as "touch" for mashes.
+  # * Under Bang (<tt>_</tt>): Like Bang, but returns a new Mash rather than creating a key.  Used to test existance in deep Mashes.
+  #
+  # == Basic Example
+  #
+  #   mash = Mash.new
+  #   mash.name? # => false
+  #   mash.name = "Bob"
+  #   mash.name # => "Bob"
+  #   mash.name? # => true
+  #
+  # == Hash Conversion  Example
+  #
+  #   hash = {:a => {:b => 23, :d => {:e => "abc"}}, :f => [{:g => 44, :h => 29}, 12]}
+  #   mash = Mash.new(hash)
+  #   mash.a.b # => 23
+  #   mash.a.d.e # => "abc"
+  #   mash.f.first.g # => 44
+  #   mash.f.last # => 12
+  #
+  # == Bang Example
+  #
+  #   mash = Mash.new
+  #   mash.author # => nil
+  #   mash.author! # => <Mash>
+  #
+  #   mash = Mash.new
+  #   mash.author!.name = "Michael Bleigh"
+  #   mash.author # => <Mash name="Michael Bleigh">
+  #
+  # == Under Bang Example
+  #
+  #   mash = Mash.new
+  #   mash.author # => nil
+  #   mash.author_ # => <Mash>
+  #   mash.author_.name # => nil
+  #
+  #   mash = Mash.new
+  #   mash.author_.name = "Michael Bleigh"  (assigned to temp object)
+  #   mash.author # => <Mash>
+  #
+  class Mash < Hashie::Hash
+    include Hashie::PrettyInspect
+    alias_method :to_s, :inspect
+
+    # If you pass in an existing hash, it will
+    # convert it to a Mash including recursively
+    # descending into arrays and hashes, converting
+    # them as well.
+    def initialize(source_hash = nil, default = nil, &blk)
+      deep_update(source_hash) if source_hash
+      default ? super(default) : super(&blk)
+    end
+
+    class << self; alias [] new; end
+
+    def id #:nodoc:
+      key?("id") ? self["id"] : super
+    end
+
+    def type #:nodoc:
+      key?("type") ? self["type"] : super
+    end
+
+    alias_method :regular_reader, :[]
+    alias_method :regular_writer, :[]=
+
+    # Retrieves an attribute set in the Mash. Will convert
+    # any key passed in to a string before retrieving.
+    def [](key)
+      value = regular_reader(convert_key(key))
+      yield value if block_given?
+      value
+    end
+
+    # Sets an attribute in the Mash. Key will be converted to
+    # a string before it is set, and Hashes will be converted
+    # into Mashes for nesting purposes.
+    def []=(key,value) #:nodoc:
+      regular_writer(convert_key(key), convert_value(value))
+    end
+
+    # This is the bang method reader, it will return a new Mash
+    # if there isn't a value already assigned to the key requested.
+    def initializing_reader(key)
+      ck = convert_key(key)
+      regular_writer(ck, self.class.new) unless key?(ck)
+      regular_reader(ck)
+    end
+
+    # This is the under bang method reader, it will return a temporary new Mash
+    # if there isn't a value already assigned to the key requested.
+    def underbang_reader(key)
+      ck = convert_key(key)
+      if key?(ck)
+        regular_reader(ck)
+      else
+        self.class.new
+      end
+    end
+
+    def delete(key)
+      super(convert_key(key))
+    end
+
+    alias_method :regular_dup, :dup
+    # Duplicates the current mash as a new mash.
+    def dup
+      self.class.new(self, self.default)
+    end
+
+    def key?(key)
+      super(convert_key(key))
+    end
+    alias_method :has_key?, :key?
+    alias_method :include?, :key?
+    alias_method :member?, :key?
+
+    # Performs a deep_update on a duplicate of the
+    # current mash.
+    def deep_merge(other_hash)
+      dup.deep_update(other_hash)
+    end
+    alias_method :merge, :deep_merge
+
+    # Recursively merges this mash with the passed
+    # in hash, merging each hash in the hierarchy.
+    def deep_update(other_hash)
+      other_hash.each_pair do |k,v|
+        key = convert_key(k)
+        if regular_reader(key).is_a?(Mash) and v.is_a?(::Hash)
+          regular_reader(key).deep_update(v)
+        else
+          regular_writer(key, convert_value(v, true))
+        end
+      end
+      self
+    end
+    alias_method :deep_merge!, :deep_update
+    alias_method :update, :deep_update
+    alias_method :merge!, :update
+
+    # Performs a shallow_update on a duplicate of the current mash
+    def shallow_merge(other_hash)
+      dup.shallow_update(other_hash)
+    end
+
+    # Merges (non-recursively) the hash from the argument,
+    # changing the receiving hash
+    def shallow_update(other_hash)
+      other_hash.each_pair do |k,v|
+        regular_writer(convert_key(k), convert_value(v, true))
+      end
+      self
+    end
+
+   # Will return true if the Mash has had a key
+   # set in addition to normal respond_to? functionality.
+   def respond_to?(method_name, include_private=false)
+     return true if key?(method_name)
+     super
+   end
+
+   def method_missing(method_name, *args, &blk)
+     return self.[](method_name, &blk) if key?(method_name)
+     match = method_name.to_s.match(/(.*?)([?=!_]?)$/)
+     case match[2]
+     when "="
+       self[match[1]] = args.first
+     when "?"
+       !!self[match[1]]
+     when "!"
+       initializing_reader(match[1])
+     when "_"
+       underbang_reader(match[1])
+     else
+       default(method_name, *args, &blk)
+     end
+   end
+
+    protected
+
+    def convert_key(key) #:nodoc:
+      key.to_s
+    end
+
+    def convert_value(val, duping=false) #:nodoc:
+      case val
+        when self.class
+          val.dup
+        when ::Hash
+          val = val.dup if duping
+          self.class.new(val)
+        when Array
+          val.collect{ |e| convert_value(e) }
+        else
+          val
+      end
+    end
+  end
+end