wahashie 1.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 258e46712a6b4ef449c044714d29ad3ba3ea6188
+  data.tar.gz: 276f1cc363c7b4b9b842c7a6edee29663507c479
+SHA512:
+  metadata.gz: bbcb4e8a70d26344547085d4a4a07fdc730899e9b8481ddefaa0541c193558dff9e2b0baf278359e9de3db8a5e5b78fc3679024568e8bf2a76a162df383f0003
+  data.tar.gz: de962728e1af3e83e9bc5bab255de03d00882c27b2c9d0e1d2675e8c5451ffa31f67b6cd4eb5488143ac6867925ce27c533a5dca20ac481e8cc1b275e2ea9728

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,8 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg
+*.gem
+.bundle
+.rvmrc

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+--format=nested

data/.travis.yml

@@ -0,0 +1,7 @@
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - rbx
+  - ree
+  - ruby-head
+  - jruby

data/.yardopts

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

data/Gemfile

@@ -0,0 +1,2 @@
+source 'http://rubygems.org'
+gemspec

data/Gemfile.lock

@@ -0,0 +1,37 @@
+PATH
+  remote: .
+  specs:
+    wahashie (1.2.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    guard (0.5.1)
+      thor (~> 0.14.6)
+    guard-rspec (0.4.0)
+      guard (>= 0.4.0)
+    rake (0.9.2)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+    thor (0.14.6)
+
+PLATFORMS
+  java
+  ruby
+
+DEPENDENCIES
+  guard
+  guard-rspec
+  rake (~> 0.9.2)
+  rspec (~> 2.5)
+  wahashie!
+
+BUNDLED WITH
+   1.15.4

data/Guardfile

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

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Intridea, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,120 @@
+= Wahashie
+
+Wahashie is a growing collection of tools that extend Hashes and make
+them more useful.
+
+== Installation
+
+Wahashie is available as a RubyGem:
+
+    gem install wahashie
+
+== 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 = Wahashie::Mash.new
+    mash.name? # => false
+    mash.name # => nil
+    mash.name = "My Mash"
+    mash.name # => "My Mash"
+    mash.name? # => true
+    mash.inspect # => <Wahashie::Mash name="My Mash">
+
+    mash = Mash.new
+    # use bang methods for multi-level assignment
+    mash.author!.name = "Michael Bleigh"
+    mash.author # => <Wahashie::Mash name="Michael Bleigh">
+
+<b>Note:</b> The <tt>?</tt> 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
+<tt>mash.key?('some_key')</tt> 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 execption if unset.
+
+=== Example:
+
+    class Person < Wahashie::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 < Wahashie::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')
+
+== 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 = Wahashie::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 = Wahashie::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 = Wahashie::Clash.new
+    c.where(:abc => 'def').where(:hgi => 123)
+    c # => {:where => {:abc => 'def', :hgi => 123}}
+
+
+== Note on Patches/Pull Requests
+
+* Fork the project.
+* 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. Bonus points for topic branches.
+
+== Authors
+
+* Michael Bleigh
+
+== Copyright
+
+Copyright (c) 2009 Intridea, Inc (http://intridea.com/). See LICENSE for details.

data/Rakefile

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'bundler'
+Bundler.setup
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new do |spec|
+  # spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+end
+
+task :default => :spec

data/lib/wahashie.rb

@@ -0,0 +1,9 @@
+module Wahashie
+  autoload :HashExtensions, 'wahashie/hash_extensions'
+  autoload :PrettyInspect, 'wahashie/hash_extensions'
+  autoload :Hash, 'wahashie/hash'
+  autoload :Trash, 'wahashie/trash'
+  autoload :Mash, 'wahashie/mash'
+  autoload :Dash, 'wahashie/dash'
+  autoload :Clash, 'wahashie/clash'
+end

data/lib/wahashie/clash.rb

@@ -0,0 +1,86 @@
+require 'wahashie/hash'
+
+module Wahashie
+  #
+  # A Clash is a "Chainable Lazy Hash". Inspired by libraries such as Arel,
+  # a Clash allows you to chain together method arguments to build a 
+  # hash, something that's especially useful if you're doing something
+  # like constructing a complex options hash. Here's a basic example:
+  # 
+  #     c = Wahashie::Clash.new.conditions(:foo => 'bar').order(:created_at)
+  #     c # => {:conditions => {:foo => 'bar'}, :order => :created_at}
+  #
+  # Clash provides another way to create sub-hashes by using bang notation.
+  # You can dive into a sub-hash by providing a key with a bang and dive
+  # back out again with the _end! method. Example:
+  #
+  #     c = Wahashie::Clash.new.conditions!.foo('bar').baz(123)._end!.order(:created_at)
+  #     c # => {:conditions => {:foo => 'bar', :baz => 123}, :order => :created_at}
+  #
+  # Because the primary functionality of Clash is to build options objects,
+  # all keys are converted to symbols since many libraries expect symbols explicitly
+  # for keys.
+  #
+  class Clash < ::Hash
+    class ChainError < ::StandardError; end
+    # The parent Clash if this Clash was created via chaining.
+    attr_reader :_parent
+    
+    # Initialize a new clash by passing in a Hash to
+    # convert and, optionally, the parent to which this
+    # Clash is chained.
+    def initialize(other_hash = {}, parent = nil)
+      @_parent = parent
+      other_hash.each_pair do |k, v|
+        self[k.to_sym] = v
+      end
+    end
+    
+    # Jump back up a level if you are using bang method
+    # chaining. For example:
+    #
+    # c = Wahashie::Clash.new.foo('bar')
+    # c.baz!.foo(123) # => c[:baz]
+    # c.baz!._end! # => c
+    def _end!
+      self._parent
+    end
+    
+    def id(*args) #:nodoc:
+      method_missing(:id, *args)
+    end
+    
+    def merge_store(key, *args) #:nodoc:
+      case args.length
+        when 1
+          val = args.first
+          val = self[key].merge(val) if self[key].is_a?(::Hash) && val.is_a?(::Hash)
+        else
+          val = args
+      end
+
+      self[key.to_sym] = val
+      self
+    end
+    
+    def method_missing(name, *args) #:nodoc:
+      name = name.to_s
+      if name.match(/!$/) && args.empty?
+        key = name[0...-1].to_sym
+        
+        if self[key].nil?
+          self[key] = Clash.new({}, self)
+        elsif self[key].is_a?(::Hash) && !self[key].is_a?(Clash)
+          self[key] = Clash.new(self[key], self)
+        else
+          raise ChainError, "Tried to chain into a non-hash key."
+        end
+        
+        self[key]
+      elsif args.any?
+        key = name.to_sym
+        self.merge_store(key, *args)
+      end
+    end
+  end
+end

data/lib/wahashie/dash.rb

@@ -0,0 +1,150 @@
+require 'wahashie/hash'
+require 'set'
+
+module Wahashie
+  # 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 < Wahashie::Hash
+    include Wahashie::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