defined_hash 0.1.0

data/.document

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

data/.gitignore

@@ -0,0 +1,22 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+.baretest_id_*

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Jonathan Stott
+
+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,42 @@
+= Defined Hash
+
+A hash with defined keys
+
+This is somewhat similar to the 'Dash' provided by Hashie, but it has
+hashidator validations baked in, and in addition, supports the idea of
+optional columns.  It also allows for sensible merging of such values.
+Property definition is based on the hashidator validation syntax.
+
+    class Person < DefinedHash
+      property :name,       String    # name is a string
+      property :emails,     [String]  # Array of strings for email addresses
+      property :addresses,  [Address] # Supports nesting of defined hashes
+    end
+
+It was written with mongodb in mind, as all the existing mappers were massively
+complex for what I wanted.
+
+== Who should use DefinedHash?
+
+* People who want a simple hash schema with validations
+* People who want something lightweight and fast
+
+== Who shouldn't use DefinedHash?
+
+* People who want error messages
+* People with a very complex schema
+* People who want an ORM/ODM.
+
+== 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.
+
+== Copyright
+
+Copyright (c) 2010 Jonathan Stott. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,27 @@
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "defined_hash"
+    gem.summary = %Q{Defined hashlike objects, with validations}
+    gem.description = %Q{Defined hashlike objects, with validations.  For simple schema definitions and checking they're followed}
+    gem.email = "jonathan.stott@gmail.com"
+    gem.homepage = "http://github.com/namelessjon/defined_hash"
+    gem.authors = ["Jonathan Stott"]
+    gem.add_dependency "hashidator"
+    gem.add_development_dependency "baretest", ">= 0"
+    gem.add_development_dependency "yard", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/defined_hash.rb

@@ -0,0 +1,168 @@
+require 'hashidator'
+
+# A hash with defined keys
+#
+# This is somewhat similar to the 'Dash' provided by Hashie, but it has
+# hashidator validations baked in, and in addition, supports the idea of
+# optional columns.  It also allows for sensible merging of such values.
+# Property definition is based on the hashidator validation syntax.
+#
+# @example
+#   class Person < DefinedHash
+#     property :name,       String    # name is a string
+#     property :emails,     [String]  # Array of strings for email addresses
+#     property :addresses,  [Address] # Supports nesting of defined hashes
+#   end
+#
+class DefinedHash < Hash
+
+  def initialize(attributes={})
+    attributes.each do |name, value|
+      self[name] = value
+    end
+  end
+
+
+  # Assign a value to the hash
+  #
+  # Assigns a value to the defined hash.  This does a certain amount of
+  # typecasting, for example converting properties into arrays, or DefinedHashes
+  #
+  # @param name [Symbol,String] Property name to assign
+  # @param value [Object]       Value to assign
+  #
+  # @return [Object]            The value just assigned.
+  #
+  # @api public
+  def []=(name, value)
+    if (property_name = self.class.property_names.detect { |pn| pn == name.to_s })
+      property_name = property_name.to_sym # we know it's a defined name, so this isn't a leak.
+      property      = self.class.properties[property_name]
+      case property
+      when Array
+        value = self.class.typecast_value_to_array(property, value)
+        if has_key?(property_name)
+          self[property_name].concat( value )
+        else
+          super(property_name, value)
+        end
+      when Class
+        super(property_name, self.class.typecast_value_to_class(property, value))
+      else
+        super(property_name, value)
+      end
+    end
+    # ignore properties without names
+    value
+  end
+
+  # Define a property for the hash
+  #
+  # This is used to define the hash schema.  Property definitions look somewhat
+  # similar to DataMapper ones, but the types actually define hashidator
+  # validation classes, as well as defining the schema.
+  #
+  # @param name [Symbol] The name of the property
+  # @param type [Object] The type of the property
+  #
+  # @option opts [Boolean] :optional (false) If true, this property won't be validated if it isn't there.
+  #
+  # @return nil
+  #
+  # @api public
+  def self.property(name, type, opts={})
+    # use a DefinedHash's inbuilt validations if we have a defined hash
+    klass_validator = class_validator_for(type)
+    klass_validator = (Array === klass_validator and
+                       Class === klass_validator.first and
+                       klass_validator.first < DefinedHash) ? [class_validator_for(klass_validator.first)] : klass_validator
+
+    # optional validations done via proc
+    validator = opts.fetch(:optional, false) ? proc { |v| v.nil? ? true : klass_validator } : klass_validator
+
+    (@properties ||= {})[name]  = type
+    (@validations ||= {})[name] = validator
+    nil
+  end
+
+  def self.property_names
+    properties.keys.map { |p| p.to_s }
+  end
+
+  def self.properties
+    (@properties || {})
+  end
+
+  def self.validations
+    (@validations || {})
+  end
+
+  # validates the hash with hashidator
+  #
+  # @return [Boolean] true/false depending on validation
+  #
+  # @api public
+  def valid?
+    Hashidator.validate(self.class.validations, self)
+  end
+
+  # Merges in another hash, destroying original values
+  #
+  # @param hash [Hash] The hash to merge
+  #
+  # @return [self] The new hash
+  def merge!(hash)
+    hash.each do |key, value|
+      self[key] = value
+    end
+    self
+  end
+
+  def to_hash
+    out = {}
+    keys.each do |k|
+      out[k] = self[k]
+    end
+    out
+  end
+
+
+  private
+  def self.class_validator_for(type)
+    (Class === type and type < DefinedHash) ? proc { |v| v.valid? } : type
+  end
+
+
+  def self.typecast_value_to_class(klass, value)
+    if klass < DefinedHash # if we have a defined hash, make it new!
+      value = klass.new(value) unless klass === value
+    end
+    value
+  end
+
+
+
+  def self.typecast_value_to_array(property, value)
+    value = (Array === value) ? value : [value]
+    case property.first
+    when Hash
+      return value.map { |v| self.typecast_value_to_hash(property.first, v) }
+    when Class
+      return value.map { |v| self.typecast_value_to_class(property.first, v) }
+    end
+    value
+  end
+
+  def self.typecast_value_to_hash(property, values)
+    hash = {}
+    keys = property.keys.map { |k| k.to_s }
+    values.each do |name, value|
+      name = name.to_s
+      if keys.include?(name)
+        hash[name.to_sym] = value
+      end
+    end
+    hash
+  end
+
+end

data/test/setup.rb

@@ -0,0 +1,2 @@
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+require 'baretest'

data/test/suite/lib/hash.rb

@@ -0,0 +1,197 @@
+#!/usr/bin/ruby
+# Jonathan D. Stott <jonathan.stott@gmail.com>
+require 'defined_hash'
+BareTest.suite "DefinedHash" do
+  setup do
+    class ::Person < DefinedHash
+      property :name, String
+      property :page, String
+    end
+  end
+
+  teardown do
+    Object.send(:remove_const, :Person)
+  end
+
+  suite ".properties" do
+    assert "properties list is correct" do
+      equal(Person.properties, {:name => String, :page => String})
+    end
+  end
+
+  suite ".new", :provides => :new do
+    assert "Basic .new works" do
+      Person.new
+    end
+
+    assert ".new with properties works" do
+      Person.new(:name => 'foo')
+    end
+
+    assert ".new with invalid properties works" do
+      Person.new(:name => 'foo', :num => 1)
+    end
+  end
+
+  suite "A DefinedHash", :depends_on => :new do
+    setup do
+      @person         = Person.new(:name => 'Bob', 'page' => 'bob', :num => 1)
+    end
+
+    assert "has valid properties set" do
+      @person[:name] == 'Bob'
+    end
+
+    assert "has strings set" do
+      @person[:page] == 'bob'
+    end
+
+    assert "Doesn't have non-valid keys set" do
+      @person.has_key?(:num) == false
+    end
+  end
+
+  suite "DefinedHash properties", :depends_on => :new do
+    setup do
+      class ::Address < DefinedHash
+        property :name, String
+        property :postcode, String
+      end
+
+      class ::Email < DefinedHash
+        property :name, String
+        property :email, String
+      end
+
+      class ::Person
+        property :address, ::Address
+        property :emails, [::Email]
+      end
+    end
+
+    teardown do
+      Object.send(:remove_const, :Address)
+    end
+
+    suite do
+      setup :person, [
+        {:name => 'name', :address => { :name => 'home', :postcode => 'code' }},
+        {:name => 'name', :address => { 'name' => 'home', 'postcode' => 'code' }}
+#        {:name => 'name', :address => Address.new('name' => 'home', 'postcode' => 'code' )}
+      ] do |person|
+        @person = Person.new(person)
+      end
+
+
+      assert ":person has address name set correctly" do
+        @person[:address][:name] == 'home'
+      end
+
+      assert ":person has address postcode set correctly" do
+        @person[:address][:postcode] == 'code'
+      end
+    end
+  end
+
+  suite "Array properties", :depends_on => :new do
+    setup do
+      class ::Person
+        property :numbers, [String]
+        property :emails,   [{:name => String}]
+      end
+    end
+
+    assert "An array property is assigned as an array" do
+      @person = Person.new(:numbers => %w{5551234})
+      equal_unordered(%w{5551234}, @person[:numbers])
+    end
+
+    assert "A non-array property is assigned as an array" do
+      @person = Person.new(:numbers => "5551234")
+      equal_unordered(%w{5551234}, @person[:numbers])
+    end
+
+    assert "A hash in array is added properly" do
+      @person = Person.new(:emails => { 'name' => 'gmail', :foo => 'bar'})
+      equal_unordered([{:name => 'gmail'}], @person[:emails])
+    end
+    assert "A hash in array is added properly" do
+      @person = Person.new(:emails => [{ 'name' => 'gmail', :foo => 'bar'}])
+      equal_unordered([{:name => 'gmail'}], @person[:emails])
+    end
+
+
+  end
+
+
+
+  suite "Testing validity", :depends_on => :new do
+    setup do
+      class ::Email < DefinedHash
+        property :name, String, :optional => true
+        property :email, String
+      end
+
+      class ::Number < DefinedHash
+        property :name, String, :optional => true
+        property :number, String
+      end
+
+      class ::Person
+        property :nick, String, :optional => true
+        property :email, Email, :optional => true
+        property :numbers, [Number], :optional => true
+      end
+    end
+
+    suite "invalid" do
+      setup :invalid_person, [
+          {:name => 'name'},
+          {:page => 'page'},
+          { :name => 'name', :page => 1 },
+          { :name => 1, :page => 'page' },
+          {:name => 'name', :page => 'page', :email => { :name => 'home'}},
+          {:name => 'name', :page => 'page', :email => { :email => 'a@example.com'}, :numbers => [{ :number => "555-1234" }, { }]},
+          {:name => 'name', :page => 'page', :nick => 2 }
+        ] do |invalid_person|
+        @person = Person.new(invalid_person)
+      end
+
+      assert ":invalid_person is invalid" do
+        @person.valid? == false
+      end
+    end
+
+    suite "valid" do
+      setup :valid_person, [
+        {:name => 'name', :page => 'page'},
+        {:name => 'name', :page => 'page', :email => { :name => 'home', :email => 'a@example.com'}},
+        {:name => 'name', :page => 'page', :email => { :email => 'a@example.com'}},
+        {:name => 'name', :page => 'page', :email => { :email => 'a@example.com'}, :numbers => [{ :number => "555-1234" }]},
+        {:name => 'name', :page => 'page', :nick => 'namz' }
+      ] do |valid_person|
+        @person = Person.new(valid_person)
+      end
+
+      assert ":valid_person is valid" do
+        @person.valid? == true
+      end
+    end
+  end
+
+  suite "merge!", :depends_on => :new do
+    setup do
+      @person = Person.new(:name => 'name', :page => 'p')
+    end
+
+    assert "properties are merged correctly from a hash" do
+      @person.merge!(:page => 'page', :foo => 'bar')
+      @person == Person.new(:name => 'name', :page => 'page')
+    end
+
+    assert "properties are merged correctly from a person" do
+      @person.merge!(Person.new(:page => 'page', :foo => 'bar'))
+      @person == Person.new(:name => 'name', :page => 'page')
+    end
+  end
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification 
+name: defined_hash
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Jonathan Stott
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-05 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hashidator
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: baretest
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+description: Defined hashlike objects, with validations.  For simple schema definitions and checking they're followed
+email: jonathan.stott@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/defined_hash.rb
+- test/setup.rb
+- test/suite/lib/hash.rb
+has_rdoc: true
+homepage: http://github.com/namelessjon/defined_hash
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Defined hashlike objects, with validations
+test_files: 
+- test/suite/lib/hash.rb
+- test/setup.rb