hashie 1.2.0 → 2.0.0

data/.gitignore

@@ -6,3 +6,4 @@ pkg
 *.gem
 .bundle
 .rvmrc
+Gemfile.lock

data/.yardopts

@@ -0,0 +1 @@
+-m markdown

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# CHANGELOG
+
+## 2.0.0
+
+* update gemspec with license info jordimassaguerpla #72
+* fix readme typo jcamenisch #71
+* initialize with merge coerces values mattfawcett #27
+* Hashie::Extensions::Coercion coerce_keys takes arguments mattfawcett #28
+* Trash removes translated values on initialization sleverbor #39
+* Mash#fetch works with symbol or string keys arthwood #66
+* Hashie::Hash inherits from ::Hash to avoid ambiguity meh, orend #49
+* update respond_to? method signature to match ruby core definition dlupu #62
+* DeepMerge extension nashby #41
+* Dash defaults are dup'ed before assigned ohrite #63
+* remove id, type, and object_id as special allowable keys jch #77
+* merge and update accepts a block jch #78

data/CONTRIBUTING.md

@@ -0,0 +1,27 @@
+## Note on Patches/Pull Requests
+
+Thanks for taking the time to contribute back! To make it easier for us to
+review your changes, try to follow these guidelines:
+
+* Keep changesets small and on topic. Itching to refactor or clean something
+  up? Do it in a separate branch.
+* Stay consistent with existing code conventions.
+* Break changes into smaller logical commits.
+
+To propose a change:
+
+* [Fork the project.](https://help.github.com/articles/fork-a-repo)
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* [Send me a pull request](https://help.github.com/articles/using-pull-requests). Bonus points for topic branches.
+* [Check that your pull request passes the build](https://travis-ci.org/intridea/hashie/pull_requests).
+
+## Bug triage
+
+Have a problem? File an [issue here](https://github.com/intridea/hashie/issues).
+
+To make bug squashing easier, include the following in your issue:
+
+* What version of hashie are you using?
+* Is it still a problem in master?

data/Guardfile

@@ -1,5 +1,5 @@
 guard 'rspec' do
   watch(%r{^spec/.+_spec\.rb})
-  watch(%r{^lib/(.+)\.rb})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch(%r{^lib/(.+)\.rb})     { |m| "spec/#{m[1]}_spec.rb" }
   watch('spec/spec_helper.rb') { "spec" }
 end

data/README.markdown

@@ -0,0 +1,240 @@
+**Note:** This documentation is for the unreleased version 2.0 of
+Hashie. See the [1-1-stable branch](https://github.com/intridea/hashie/tree/1-1-stable) for documentation of the released version.
+
+# Hashie [![Build Status](https://secure.travis-ci.org/intridea/hashie.png)](http://travis-ci.org/intridea/hashie) [![Dependency Status](https://gemnasium.com/intridea/hashie.png)](https://gemnasium.com/intridea/hashie)
+
+Hashie is a growing collection of tools that extend Hashes and make
+them more useful.
+
+## Installation
+
+Hashie is available as a RubyGem:
+
+    gem install hashie
+
+## Hash Extensions
+
+New to version 2.0 of Hashie, the library has been broken up into a
+number of atomically includeable Hash extension modules as described
+below. This provides maximum flexibility for users to mix and match
+functionality while maintaining feature parity with earlier versions of
+Hashie.
+
+Any of the extensions listed below can be mixed into a class by
+`include`-ing `Hashie::Extensions::ExtensionName`.
+
+### Coercion
+
+Coercions allow you to set up "coercion rules" based either on the key
+or the value type to massage data as it's being inserted into the Hash.
+Key coercions might be used, for example, in lightweight data modeling
+applications such as an API client:
+
+    class Tweet < Hash
+      include Hashie::Extensions::Coercion
+      coerce_key :user, User
+    end
+
+    user_hash = {:name => "Bob"}
+    Tweet.new(:user => user_hash)
+    # => automatically calls User.coerce(user_hash) or
+    #    User.new(user_hash) if that isn't present.
+
+Value coercions, on the other hand, will coerce values based on the type
+of the value being inserted. This is useful if you are trying to build a
+Hash-like class that is self-propagating.
+
+    class SpecialHash < Hash
+      include Hashie::Extensions::Coercion
+      coerce_value Hash, SpecialHash
+
+      def initialize(hash = {})
+        super
+        hash.each_pair do |k,v|
+          self[k] = v
+        end
+      end
+    end
+
+### KeyConversion
+
+The KeyConversion extension gives you the convenience methods of
+`symbolize_keys` and `stringify_keys` along with their bang
+counterparts. You can also include just stringify or just symbolize with
+`Hashie::Extensions::StringifyKeys` or `Hashie::Extensions::SymbolizeKeys`.
+
+### MergeInitializer
+
+The MergeInitializer extension simply makes it possible to initialize a
+Hash subclass with another Hash, giving you a quick short-hand.
+
+### MethodAccess
+
+The MethodAccess extension allows you to quickly build method-based
+reading, writing, and querying into your Hash descendant. It can also be
+included as individual modules, i.e. `Hashie::Extensions::MethodReader`,
+`Hashie::Extensions::MethodWriter` and `Hashie::Extensions::MethodQuery`
+
+    class MyHash < Hash
+      include Hashie::Extensions::MethodAccess
+    end
+
+    h = MyHash.new
+    h.abc = 'def'
+    h.abc  # => 'def'
+    h.abc? # => true
+
+### IndifferentAccess
+
+This extension can be mixed in to instantly give you indifferent access
+to your Hash subclass. This works just like the params hash in Rails and
+other frameworks where whether you provide symbols or strings to access
+keys, you will get the same results.
+
+A unique feature of Hashie's IndifferentAccess mixin is that it will
+inject itself recursively into subhashes *without* reinitializing the
+hash in question. This means you can safely merge together indifferent
+and non-indifferent hashes arbitrarily deeply without worrying about
+whether you'll be able to `hash[:other][:another]` properly.
+
+### DeepMerge
+
+This extension allow you to easily include a recursive merging
+system to any Hash descendant:
+
+    class MyHash < Hash
+      include Hashie::Extensions::DeepMerge
+    end
+
+    h1 = MyHash.new
+    h2 = MyHash.new
+
+    h1 = {:x => {:y => [4,5,6]}, :z => [7,8,9]}
+    h2 = {:x => {:y => [7,8,9]}, :z => "xyz"}
+
+    h1.deep_merge(h2) #=> { :x => {:y => [7, 8, 9]}, :z => "xyz" }
+    h2.deep_merge(h1) #=> { :x => {:y => [4, 5, 6]}, :z => [7, 8, 9] }
+
+## Mash
+
+Mash is an extended Hash that gives simple pseudo-object functionality
+that can be built from hashes and easily extended. It is designed to
+be used in RESTful API libraries to provide easy object-like access
+to JSON and XML parsed hashes.
+
+### Example:
+
+    mash = Hashie::Mash.new
+    mash.name? # => false
+    mash.name # => nil
+    mash.name = "My Mash"
+    mash.name # => "My Mash"
+    mash.name? # => true
+    mash.inspect # => <Hashie::Mash name="My Mash">
+
+    mash = Mash.new
+    # use bang methods for multi-level assignment
+    mash.author!.name = "Michael Bleigh"
+    mash.author # => <Hashie::Mash name="Michael Bleigh">
+
+    mash = Mash.new
+    # use under-bang methods for multi-level testing
+    mash.author_.name? # => false
+    mash.inspect # => <Hashie::Mash>
+
+**Note:** The `?` method will return false if a key has been set
+to false or nil. In order to check if a key has been set at all, use the
+`mash.key?('some_key')` method instead.
+
+## Dash
+
+Dash is an extended Hash that has a discrete set of defined properties
+and only those properties may be set on the hash. Additionally, you
+can set defaults for each property. You can also flag a property as
+required. Required properties will raise an exception if unset.
+
+### Example:
+
+    class Person < Hashie::Dash
+      property :name, :required => true
+      property :email
+      property :occupation, :default => 'Rubyist'
+    end
+
+    p = Person.new # => ArgumentError: The property 'name' is required for this Dash.
+
+    p = Person.new(:name => "Bob")
+    p.name # => 'Bob'
+    p.name = nil # => ArgumentError: The property 'name' is required for this Dash.
+    p.email = 'abc@def.com'
+    p.occupation   # => 'Rubyist'
+    p.email        # => 'abc@def.com'
+    p[:awesome]    # => NoMethodError
+    p[:occupation] # => 'Rubyist'
+
+## Trash
+
+A Trash is a Dash that allows you to translate keys on initialization.
+It is used like so:
+
+    class Person < Hashie::Trash
+      property :first_name, :from => :firstName
+    end
+
+This will automatically translate the <tt>firstName</tt> key to <tt>first_name</tt>
+when it is initialized using a hash such as through:
+
+    Person.new(:firstName => 'Bob')
+
+Trash also supports translations using lambda, this could be useful when dealing with
+external API's. You can use it in this way:
+
+    class Result < Hashie::Trash
+      property :id, :transform_with => lambda { |v| v.to_i }
+      property :created_at, :from => :creation_date, :with => lambda { |v| Time.parse(v) }
+    end
+
+this will produce the following
+
+    result = Result.new(:id => '123', :creation_date => '2012-03-30 17:23:28')
+    result.id.class         # => Fixnum
+    result.created_at.class # => Time
+
+## Clash
+
+Clash is a Chainable Lazy Hash that allows you to easily construct
+complex hashes using method notation chaining. This will allow you
+to use a more action-oriented approach to building options hashes.
+
+Essentially, a Clash is a generalized way to provide much of the same
+kind of "chainability" that libraries like Arel or Rails 2.x's named_scopes
+provide.
+
+### Example
+
+    c = Hashie::Clash.new
+    c.where(:abc => 'def').order(:created_at)
+    c # => {:where => {:abc => 'def'}, :order => :created_at}
+
+    # You can also use bang notation to chain into sub-hashes,
+    # jumping back up the chain with _end!
+    c = Hashie::Clash.new
+    c.where!.abc('def').ghi(123)._end!.order(:created_at)
+    c # => {:where => {:abc => 'def', :ghi => 123}, :order => :created_at}
+
+    # Multiple hashes are merged automatically
+    c = Hashie::Clash.new
+    c.where(:abc => 'def').where(:hgi => 123)
+    c # => {:where => {:abc => 'def', :hgi => 123}}
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Authors
+
+* Michael Bleigh
+
+## Copyright
+
+Copyright (c) 2009-2011 Intridea, Inc. (http://intridea.com/). See LICENSE for details.

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/hashie.gemspec

@@ -1,8 +1,8 @@
 require File.expand_path('../lib/hashie/version', __FILE__)
 
 Gem::Specification.new do |gem|
-  gem.authors       = ["Michael Bleigh"]
-  gem.email         = ["michael@intridea.com"]
+  gem.authors       = ["Michael Bleigh", "Jerry Cheung"]
+  gem.email         = ["michael@intridea.com", "jollyjerry@gmail.com"]
   gem.description   = %q{Hashie is a small collection of tools that make hashes more powerful. Currently includes Mash (Mocking Hash) and Dash (Discrete Hash).}
   gem.summary       = %q{Your friendly neighborhood hash toolkit.}
   gem.homepage      = 'https://github.com/intridea/hashie'
@@ -13,9 +13,11 @@ Gem::Specification.new do |gem|
   gem.name          = "hashie"
   gem.require_paths = ['lib']
   gem.version       = Hashie::VERSION
+  gem.license       = "MIT"
 
   gem.add_development_dependency 'rake', '~> 0.9.2'
   gem.add_development_dependency 'rspec', '~> 2.5'
   gem.add_development_dependency 'guard'
   gem.add_development_dependency 'guard-rspec'
+  gem.add_development_dependency 'growl'
 end

data/lib/hashie.rb

@@ -1,9 +1,23 @@
 module Hashie
+  autoload :Clash,          'hashie/clash'
+  autoload :Dash,           'hashie/dash'
+  autoload :Hash,           'hashie/hash'
   autoload :HashExtensions, 'hashie/hash_extensions'
-  autoload :PrettyInspect, 'hashie/hash_extensions'
-  autoload :Hash, 'hashie/hash'
-  autoload :Trash, 'hashie/trash'
-  autoload :Mash, 'hashie/mash'
-  autoload :Dash, 'hashie/dash'
-  autoload :Clash, 'hashie/clash'
+  autoload :Mash,           'hashie/mash'
+  autoload :PrettyInspect,  'hashie/hash_extensions'
+  autoload :Trash,          'hashie/trash'
+
+  module Extensions
+    autoload :Coercion,          'hashie/extensions/coercion'
+    autoload :DeepMerge,         'hashie/extensions/deep_merge'
+    autoload :KeyConversion,     'hashie/extensions/key_conversion'
+    autoload :IndifferentAccess, 'hashie/extensions/indifferent_access'
+    autoload :MergeInitializer,  'hashie/extensions/merge_initializer'
+    autoload :MethodAccess,      'hashie/extensions/method_access'
+    autoload :MethodQuery,       'hashie/extensions/method_access'
+    autoload :MethodReader,      'hashie/extensions/method_access'
+    autoload :MethodWriter,      'hashie/extensions/method_access'
+    autoload :StringifyKeys,     'hashie/extensions/key_conversion'
+    autoload :SymbolizeKeys,     'hashie/extensions/key_conversion'
+  end
 end

data/lib/hashie/dash.rb

@@ -12,8 +12,8 @@ module Hashie
   #
   # It is preferrable to a Struct because of the in-class
   # API for defining properties as well as per-property defaults.
-  class Dash < Hashie::Hash
-    include Hashie::PrettyInspect
+  class Dash < Hash
+    include PrettyInspect
     alias_method :to_s, :inspect
 
     # Defines a property on the Dash. Options are
@@ -90,12 +90,14 @@ module Hashie
       super(&block)
 
       self.class.defaults.each_pair do |prop, value|
-        self[prop] = value
+        self[prop] = begin
+          value.dup
+        rescue TypeError
+          value
+        end
       end
 
-      attributes.each_pair do |att, value|
-        self[att] = value
-      end if attributes
+      initialize_attributes(attributes)
       assert_required_properties_set!
     end
 
@@ -108,8 +110,13 @@ module Hashie
     def [](property)
       assert_property_exists! property
       value = super(property.to_s)
-      yield value if block_given?
-      value
+      # If the value is a lambda, proc, or whatever answers to call, eval the thing!
+      if value.is_a? Proc
+        self[property] = value.call # Set the result of the call as a value
+      else
+        yield value if block_given?
+        value
+      end
     end
 
     # Set a value on the Dash in a Hash-like way. Only works
@@ -122,6 +129,12 @@ module Hashie
 
     private
 
+      def initialize_attributes(attributes)
+        attributes.each_pair do |att, value|
+          self[att] = value
+        end if attributes
+      end
+
       def assert_property_exists!(property)
         unless self.class.property?(property)
           raise NoMethodError, "The property '#{property}' is not defined for this Dash."

data/lib/hashie/extensions/coercion.rb

@@ -0,0 +1,105 @@
+module Hashie
+  module Extensions
+    module Coercion
+      def self.included(base)
+        base.send :extend, ClassMethods
+        base.send :include, InstanceMethods
+      end
+
+      module InstanceMethods
+        def []=(key, value)
+          into = self.class.key_coercion(key) || self.class.value_coercion(value)
+
+          if value && into
+            if into.respond_to?(:coerce)
+              value = into.coerce(value)
+            else
+              value = into.new(value)
+            end
+          end
+
+          super(key, value)
+        end
+      end
+
+      module ClassMethods
+        # Set up a coercion rule such that any time the specified
+        # key is set it will be coerced into the specified class.
+        # Coercion will occur by first attempting to call Class.coerce 
+        # and then by calling Class.new with the value as an argument
+        # in either case.
+        #
+        # @param [Object] key the key or array of keys you would like to be coerced.
+        # @param [Class] into the class into which you want the key(s) coerced.
+        #
+        # @example Coerce a "user" subhash into a User object
+        #   class Tweet < Hash
+        #     include Hashie::Extensions::Coercion
+        #     coerce_key :user, User
+        #   end
+        def coerce_key(*attrs)
+          @key_coercions ||= {}
+          into = attrs.pop
+          attrs.each { |key| @key_coercions[key] = into }
+        end
+
+        alias :coerce_keys :coerce_key
+
+        # Returns a hash of any existing key coercions.
+        def key_coercions
+          @key_coercions || {}
+        end
+
+        # Returns the specific key coercion for the specified key,
+        # if one exists.
+        def key_coercion(key)
+          key_coercions[key]
+        end
+
+        # Set up a coercion rule such that any time a value of the
+        # specified type is set it will be coerced into the specified
+        # class.
+        #
+        # @param [Class] from the type you would like coerced.
+        # @param [Class] into the class into which you would like the value coerced.
+        # @option options [Boolean] :strict (true) whether use exact source class only or include ancestors
+        #
+        # @example Coerce all hashes into this special type of hash
+        #   class SpecialHash < Hash
+        #     include Hashie::Extensions::Coercion
+        #     coerce_value Hash, SpecialHash
+        #
+        #     def initialize(hash = {})
+        #       super
+        #       hash.each_pair do |k,v|
+        #         self[k] = v
+        #       end
+        #     end
+        #   end
+        def coerce_value(from, into, options = {})
+          options = {:strict => true}.merge(options)
+
+          if options[:strict]
+            (@strict_value_coercions ||= {})[from] = into
+          else
+            while from.superclass && from.superclass != Object
+              (@lenient_value_coercions ||= {})[from] = into
+              from = from.superclass
+            end
+          end
+        end
+        
+        # Return all value coercions that have the :strict rule as true.
+        def strict_value_coercions; @strict_value_coercions || {} end
+        # Return all value coercions that have the :strict rule as false.
+        def lenient_value_coercions; @value_coercions || {} end
+
+        # Fetch the value coercion, if any, for the specified object.
+        def value_coercion(value)
+          from = value.class
+          strict_value_coercions[from] || lenient_value_coercions[from] 
+        end
+      end
+    end
+  end
+end