hashie-pre 2.0.0.beta

data/lib/hashie/dash.rb

@@ -0,0 +1,150 @@
+require 'hashie/hash'
+require 'set'
+
+module Hashie
+  # A Dash is a 'defined' or 'discrete' Hash, that is, a Hash
+  # that has a set of defined keys that are accessible (with
+  # optional defaults) and only those keys may be set or read.
+  #
+  # Dashes are useful when you need to create a very simple
+  # lightweight data object that needs even fewer options and
+  # resources than something like a DataMapper resource.
+  #
+  # 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
+    alias_method :to_s, :inspect
+
+    # Defines a property on the Dash. Options are
+    # as follows:
+    #
+    # * <tt>:default</tt> - Specify a default value for this property,
+    #   to be returned before a value is set on the property in a new
+    #   Dash.
+    #
+    # * <tt>:required</tt> - Specify the value as required for this
+    #   property, to raise an error if a value is unset in a new or
+    #   existing Dash.
+    #
+    def self.property(property_name, options = {})
+      property_name = property_name.to_sym
+
+      self.properties << property_name
+
+      if options.has_key?(:default)
+        self.defaults[property_name] = options[:default]
+      elsif self.defaults.has_key?(property_name)
+        self.defaults.delete property_name
+      end
+
+      unless instance_methods.map { |m| m.to_s }.include?("#{property_name}=")
+        class_eval <<-ACCESSORS
+          def #{property_name}(&block)
+            self.[](#{property_name.to_s.inspect}, &block)
+          end
+
+          def #{property_name}=(value)
+            self.[]=(#{property_name.to_s.inspect}, value)
+          end
+        ACCESSORS
+      end
+
+      if defined? @subclasses
+        @subclasses.each { |klass| klass.property(property_name, options) }
+      end
+      required_properties << property_name if options.delete(:required)
+    end
+
+    class << self
+      attr_reader :properties, :defaults
+      attr_reader :required_properties
+    end
+    instance_variable_set('@properties', Set.new)
+    instance_variable_set('@defaults', {})
+    instance_variable_set('@required_properties', Set.new)
+
+    def self.inherited(klass)
+      super
+      (@subclasses ||= Set.new) << klass
+      klass.instance_variable_set('@properties', self.properties.dup)
+      klass.instance_variable_set('@defaults', self.defaults.dup)
+      klass.instance_variable_set('@required_properties', self.required_properties.dup)
+    end
+
+    # Check to see if the specified property has already been
+    # defined.
+    def self.property?(name)
+      properties.include? name.to_sym
+    end
+
+    # Check to see if the specified property is
+    # required.
+    def self.required?(name)
+      required_properties.include? name.to_sym
+    end
+
+    # You may initialize a Dash with an attributes hash
+    # just like you would many other kinds of data objects.
+    def initialize(attributes = {}, &block)
+      super(&block)
+
+      self.class.defaults.each_pair do |prop, value|
+        self[prop] = value
+      end
+
+      attributes.each_pair do |att, value|
+        self[att] = value
+      end if attributes
+      assert_required_properties_set!
+    end
+
+    alias_method :_regular_reader, :[]
+    alias_method :_regular_writer, :[]=
+    private :_regular_reader, :_regular_writer
+
+    # Retrieve a value from the Dash (will return the
+    # property's default value if it hasn't been set).
+    def [](property)
+      assert_property_exists! property
+      value = super(property.to_s)
+      yield value if block_given?
+      value
+    end
+
+    # Set a value on the Dash in a Hash-like way. Only works
+    # on pre-existing properties.
+    def []=(property, value)
+      assert_property_required! property, value
+      assert_property_exists! property
+      super(property.to_s, value)
+    end
+
+    private
+
+      def assert_property_exists!(property)
+        unless self.class.property?(property)
+          raise NoMethodError, "The property '#{property}' is not defined for this Dash."
+        end
+      end
+
+      def assert_required_properties_set!
+        self.class.required_properties.each do |required_property|
+          assert_property_set!(required_property)
+        end
+      end
+
+      def assert_property_set!(property)
+        if send(property).nil?
+          raise ArgumentError, "The property '#{property}' is required for this Dash."
+        end
+      end
+
+      def assert_property_required!(property, value)
+        if self.class.required?(property) && value.nil?
+          raise ArgumentError, "The property '#{property}' is required for this Dash."
+        end
+      end
+
+  end
+end

data/lib/hashie/extensions/coercion.rb

@@ -0,0 +1,101 @@
+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 you would like to be coerced.
+        # @param [Class] into the class into which you want the key 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(key, into)
+          (@key_coercions ||= {})[key] = into
+        end
+
+        # 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

data/lib/hashie/extensions/deep_merge.rb

@@ -0,0 +1,7 @@
+module Hashie
+  module Extensions
+    module DeepMerge
+      # TODO: Implement deep merging.
+    end
+  end
+end

data/lib/hashie/extensions/indifferent_access.rb

@@ -0,0 +1,110 @@
+module Hashie
+  module Extensions
+    # IndifferentAccess gives you the ability to not care
+    # whether your hash has string or symbol keys. Made famous
+    # in Rails for accessing query and POST parameters, this
+    # is a handy tool for making sure your hash has maximum
+    # utility.
+    #
+    # One unique feature of this mixin is that it will recursively
+    # inject itself into sub-hash instances without modifying
+    # the actual class of the sub-hash.
+    #
+    # @example
+    #   class MyHash < Hash
+    #     include Hashie::Extensions::MergeInitializer
+    #     include Hashie::Extensions::IndifferentAccess
+    #   end
+    #
+    #   h = MyHash.new(:foo => 'bar', 'baz' => 'blip')
+    #   h['foo'] # => 'bar'
+    #   h[:foo]  # => 'bar'
+    #   h[:baz]  # => 'blip'
+    #   h['baz'] # => 'blip'
+    #
+    module IndifferentAccess
+      def self.included(base)
+        base.class_eval do
+          alias_method :regular_writer, :[]=
+          alias_method :[]=, :indifferent_writer
+          %w(default update fetch delete key? values_at).each do |m|
+            alias_method "regular_#{m}", m
+            alias_method m, "indifferent_#{m}"
+          end
+        end
+      end
+
+      # This will inject indifferent access into an instance of
+      # a hash without modifying the actual class. This is what
+      # allows IndifferentAccess to spread to sub-hashes.
+      def self.inject!(hash)
+        (class << hash; self; end).send :include, Hashie::Extensions::IndifferentAccess
+        hash.convert!
+      end
+
+      # Injects indifferent access into a duplicate of the hash
+      # provided. See #inject!
+      def self.inject(hash)
+        inject!(hash.dup)
+      end
+
+      def convert_key(key)
+        key.to_s
+      end
+
+      # Iterates through the keys and values, reconverting them to
+      # their proper indifferent state. Used when IndifferentAccess
+      # is injecting itself into member hashes.
+      def convert!
+        keys.each do |k|
+          regular_writer convert_key(k), convert_value(self.regular_delete(k))
+        end
+        self
+      end
+
+      def convert_value(value)
+        if hash_lacking_indifference?(value)
+          Hashie::Extensions::IndifferentAccess.inject(value.dup)
+        elsif value.is_a?(::Array)
+          value.dup.replace(value.map { |e| convert_value(e) })
+        else
+          value
+        end
+      end
+      
+      def indifferent_default(key = nil)
+        return self[convert_key(key)] if key?(key)
+        regular_default(key)
+      end
+
+      def indifferent_update(other_hash)
+        return regular_update(other_hash) if hash_with_indifference?(other_hash)
+        other_hash.each_pair do |k,v|
+          self[k] = v
+        end
+      end
+      
+      def indifferent_writer(key, value);  regular_writer convert_key(key), convert_value(value) end
+      def indifferent_fetch(key, *args);   regular_fetch  convert_key(key), *args                end
+      def indifferent_delete(key);         regular_delete convert_key(key)                       end
+      def indifferent_key?(key);           regular_key?   convert_key(key)                       end
+      def indifferent_values_at(*indices); indices.map{|i| self[i] }                             end
+
+      def indifferent_access?; true end
+      
+      protected
+
+      def hash_lacking_indifference?(other)
+        other.is_a?(::Hash) &&
+        !(other.respond_to?(:indifferent_access?) &&
+          other.indifferent_access?)
+      end
+
+      def hash_with_indifference?(other)
+        other.is_a?(::Hash) &&
+        other.respond_to?(:indifferent_access?) &&
+        other.indifferent_access?
+      end
+    end
+  end
+end

data/lib/hashie/extensions/key_conversion.rb

@@ -0,0 +1,52 @@
+module Hashie
+  module Extensions
+    module StringifyKeys
+      # Convert all keys in the hash to strings.
+      #
+      # @example
+      #   test = {:abc => 'def'}
+      #   test.stringify_keys!
+      #   test # => {'abc' => 'def'}
+      def stringify_keys!
+        keys.each do |k|
+          self[k.to_s] = self.delete(k)
+        end
+        self
+      end
+
+      # Return a new hash with all keys converted
+      # to strings.
+      def stringify_keys
+        dup.stringify_keys!
+      end
+    end
+
+    module SymbolizeKeys
+      # Convert all keys in the hash to strings.
+      #
+      # @example
+      #   test = {'abc' => 'def'}
+      #   test.symbolize_keys!
+      #   test # => {:abc => 'def'}
+      def symbolize_keys!
+        keys.each do |k|
+          self[k.to_sym] = self.delete(k)
+        end
+        self
+      end
+
+      # Return a new hash with all keys converted
+      # to symbols.
+      def symbolize_keys
+        dup.symbolize_keys!
+      end
+    end
+    
+    module KeyConversion
+      def self.included(base)
+        base.send :include, SymbolizeKeys
+        base.send :include, StringifyKeys
+      end
+    end
+  end
+end

data/lib/hashie/extensions/merge_initializer.rb

@@ -0,0 +1,24 @@
+module Hashie
+  module Extensions
+    # The MergeInitializer is a super-simple mixin that allows
+    # you to initialize a subclass of Hash with another Hash
+    # to give you faster startup time for Hash subclasses. Note
+    # that you can still provide a default value as a second
+    # argument to the initializer.
+    #
+    # @example
+    #   class MyHash < Hash
+    #     include Hashie::Extensions::MergeInitializer
+    #   end
+    #
+    #   h = MyHash.new(:abc => 'def')
+    #   h[:abc] # => 'def'
+    #
+    module MergeInitializer
+      def initialize(hash = {}, default = nil, &block)
+        default ? super(default) : super(&block)
+        update(hash)
+      end
+    end
+  end
+end