hashema 0.0.2 → 0.1.0

data/README.md

@@ -2,9 +2,141 @@
 
 Hashema lets you validate JSONable objects (hashes and arrays) against a schema, and assert their validity in your RSpec examples.
 
-## Validating an object against a schema
+## Installation
 
-The API of `Hashema::Validator` consists of an initializer and two instance methods: `valid?` and `failure_message`. The initializer takes an object to validate and a schema, in that order. `valid?` will return `true` iff the object conforms to the schema. If `valid?` is `false`, `failure_message` will return a description of the failure.
+```bash
+gem install hashema
+```
+
+Or, if you're using [bundler](https://rubygems.org/gems/bundler), put this in your `Gemfile`:
+
+```bash
+gem 'hashema'
+```
+
+Hashema hooks into your RSpec config to provide the `conform_to_schema` matcher. If `rspec` is listed in your `Gemfile`, you should be able to use `conform_to_schema` in your tests with no further setup.
+
+## RSpec usage
+
+With hashema and RSpec, it's easy to ensure your JSON APIs return the data your clients expect.
+
+```ruby
+describe BlogSerializer do
+  before { @serializer = BlogSerializer.new(Blog.create) }
+
+  describe '#as_json' do
+    subject { @serializer.as_json }
+
+    SCHEMA = {
+      url: /^https?:\/\/.+/,
+      posts: [
+        { title: String,
+          published: [true, false]
+        }
+      ]
+    }
+
+    it { is_expected_to conform_to_schema SCHEMA }
+  end
+end
+```
+
+## The Schema DSL by example
+
+### Allowing any value
+
+```ruby
+expect(
+  Rotation.new('squirrel')
+).to conform_to_schema Object
+```
+
+### Checking for an exact match
+
+```ruby
+expect(
+  {error: 'not found'}
+).to conform_to_schema({error: 'not found'})
+```
+
+### Checking for membership in a class
+
+```ruby
+expect(
+  {berzerker: 'pasta'}
+).to conform_to_schema Hash
+```
+
+### Checking that a string value matches a regular expression
+
+```ruby
+expect(
+  'Hello! My name is Fridge.'
+).to conform_to_schema /^Hello! My name is \w+\.$/
+```
+
+### Checking for inclusion in a set of alternatives
+
+```ruby
+expect(
+  {is_awesome: true}
+).to conform_to_schema({is_awesome: [true, false]})
+```
+
+### Checking for inclusion in a range of legal values
+
+```ruby
+expect(
+  {kyu_rank: 17}
+).to conform_to_schema({kyu_rank: 1..30})
+```
+
+### Checking that all elements of an array share a schema
+
+```ruby
+expect(
+  [{name: 'Melody'}, {name: 'Elias'}, {name: 'Yoda'}]
+).to conform_to_schema [{name: String}]
+```
+
+### Matching an array of items that may have different schemas
+
+```ruby
+expect(
+  [{cash: '12.33'}, {credit: '28.95'}, {cash: '40.70'}]
+).to conform_to_schema(
+  [
+    [{cash: /^\d+\.\d\d$/}, {credit: /^\d+\.\d\d$/}]
+  ]
+)
+```
+
+## RSpec matcher options
+
+### with_indifferent_access
+
+Rails fans will be familiar with ActiveSupport's `HashWithIndifferentAccess`, which treats symbol and string keys as interchangeable. Calling `with_indifferent_access` on the `conform_to_schema` matcher will make the matcher similarly tolerant, allowing you to match a hash with string keys against a schema with symbol keys. This is especially useful when writing schemas for JSON, since parsed objects will always have string keys.
+
+```ruby
+get :show
+
+schema = {
+  url: /^https?:\/\/.+/,
+  posts: [
+    { title: String,
+      published: [true, false]
+    }
+  ]
+}
+
+expect(JSON(response.body)).to conform_to_schema(schema).with_indifferent_access
+```
+
+## Hashema without RSpec
+
+There are times when you want to validate the structure of a data object in your production code. For example, if your program parses data from a user-created file, you might want to check that the data you read in match the schema you expect. For such situations, you can use `Hashema::Validator`.
+
+The API of `Hashema::Validator` consists of an initializer and two instance methods: `valid?` and `failure_message`. The initializer takes an object to validate and a schema, in that order. `valid?` will return `true` iff the object conforms to the schema.
 
 ```ruby
 validator = Hashema::Validator.new(
@@ -37,8 +169,45 @@ validator = Hashema::Validator.new(
 validator.valid? # true
 ```
 
-## RSpec matcher usage
+If `valid?` is `false`, `failure_message` will return a human-readable description of the failure, which includes, at a minimum:
+
+- the path through the data structure to the point where the first mismatch occurred
+- the expected value at that point
+- the actual value
 
 ```ruby
-expect(datum).to conform_to_schema schema
+validator = Hashema::Validator.new(
+  # the object to validate
+  { blog:
+    { url: 'http://www.blagoblag.com',
+      posts: [
+        { title: 'hello',
+          published: true
+        },
+        { title: 123,
+          published: false
+        }
+      ]
+    }
+  },
+
+  # the schema
+  { blog:
+    { url: /^https?:\/\//,
+      posts: [
+        { title: String,
+          published: [true, false]
+        }
+      ]
+    }
+  }
+)
+
+validator.valid? # false
+puts validator.failure_message
+# prints:
+#   expected /blog/posts/1/title to match
+#   String
+#   but got
+#   123
 ```

data/lib/hashema.rb

@@ -1,7 +1,5 @@
 require 'hashema/validator'
-
-begin
-  require 'rspec'
-  require 'hashema/conform_to_schema'
-rescue LoadError => e
-end
+require 'hashema/version'
+require 'hashema/conform_to_schema'
+require 'hashema/compiler'
+require 'hashema/schema'

data/lib/hashema/compiler.rb

@@ -0,0 +1,38 @@
+require_relative './schema'
+
+module Hashema
+  class Compiler
+    def self.compile(thing, options={})
+      new(options).compile(thing)
+    end
+
+    def initialize(options={})
+      @options = options
+    end
+
+    def compile(thing)
+      case thing
+      when ::Array
+        if thing.size == 1
+          Hashema::Array.new(compile(thing[0]))
+        else
+          Hashema::Alternatives.new(*(thing.map { |element| compile element }))
+        end
+      when ::Hash
+        compile_hash(thing)
+      else
+        Hashema::Atom.new(thing)
+      end
+    end
+
+    private
+
+    def compile_hash(hash)
+      with_compiled_values = ::Hash[hash.map { |k, v| [k, compile(v)]}]
+      klass = @options[:indifferent_access] ?
+        Hashema::HashWithIndifferentAccess :
+        Hashema::Hash
+      klass.new(with_compiled_values)
+    end
+  end
+end

data/lib/hashema/conform_to_schema.rb

@@ -1,24 +1,71 @@
-RSpec::Matchers.define :conform_to_schema do |schema|
-  match do |actual|
-    @schema = schema
-    @actual = actual
-    @validator = Hashema::Validator.new(actual, schema)
-    @validator.valid?
-  end
+begin
+  require 'rspec'
+rescue LoadError => e
+end
 
-  def failure_message
-    @validator.failure_message
-  end
+module Hashema
+  module RSpecMatchers
+    class ConformToSchema
+      def initialize(schema)
+        @schema = schema
+        @with_indifferent_access = false
+      end
+
+      def with_indifferent_access
+        @with_indifferent_access = true
+        self
+      end
+
+      def matches?(actual)
+        @validator = Hashema::Validator.new(actual, @schema, validator_options)
+        @validator.valid?
+      end
+
+      def failure_message
+        @validator.failure_message
+      end
+
+      def failure_message_for_should
+        failure_message
+      end
 
-  def failure_message_for_should
-    failure_message
+      def failure_message_when_negated
+        # TODO: @actual is nil here. This probably doesn't work.
+        "expected\n#{@actual.inspect}\nnot to match schema\n#{@schema.inspect}"
+      end
+
+      def failure_message_for_should_not
+        failure_message_when_negated
+      end
+
+      def description
+        "match schema\n#{@schema.inspect}"
+      end
+
+      def validator_options
+        {indifferent_access: @with_indifferent_access}
+      end
+    end
+
+    def conform_to_schema(schema)
+      ConformToSchema.new(schema)
+    end
   end
+end
+
+if Kernel.const_defined? 'RSpec'
+  class Hashema::RSpecMatchers::ConformToSchema
+    include RSpec::Matchers::Composable
 
-  def failure_message_when_negated
-    "expected\n#{@actual.inspect}\nnot to match schema\n#{@schema.inspect}"
+    RSpec::Matchers.alias_matcher(
+      :an_object_conforming_to_schema,
+      :conform_to_schema
+    ) do |description|
+      description.sub("match schema\n", 'an object conforming to schema ')
+    end
   end
 
-  def failure_message_for_should_not
-    failure_message_when_negated
+  RSpec.configure do |config|
+    config.include Hashema::RSpecMatchers
   end
 end

data/lib/hashema/schema.rb

@@ -0,0 +1,259 @@
+module Hashema
+  class Schema < Struct.new(:expected)
+    # A Schema is a Comparison factory.
+    def compare(actual)
+      self.class.const_get('Comparison').new(actual, expected)
+    end
+
+    def inspect
+      expected.inspect
+    end
+  end
+
+  class Comparison < Struct.new(:actual, :expected)
+    def match?
+      mismatches.empty?
+    end
+
+    def mismatches
+      @mismatches ||= find_mismatches
+    end
+
+    private
+
+    def find_mismatches
+      raise NotImplementedError.new(
+        "#{self.class.name} must implement find_mismatches"
+      )
+    end
+  end
+
+  class Atom < Schema
+    class Comparison < Hashema::Comparison
+
+      private
+
+      def find_mismatches
+        expected === actual ? [] : [Mismatch.new(actual, expected, [])]
+      end
+    end
+  end
+
+  class Array < Schema
+    class Comparison < Hashema::Comparison
+
+      private
+
+      def find_mismatches
+        type_mismatches || element_mismatches
+      end
+
+      def type_mismatches
+        expectation = "be an Array, but got #{actual.class}"
+        actual.is_a?(::Array) ? nil : [Mismatch.new(actual, ::Array, [], expectation)]
+      end
+
+      def element_mismatches
+        actual.each_with_index.flat_map do |element, i|
+          element_comparison = expected.compare(element)
+
+          element_comparison.mismatches.map do |mismatch|
+            Mismatch.at i, mismatch
+          end
+        end
+      end
+    end
+  end
+
+  class Map < Schema
+    class Comparison < Hashema::Comparison
+
+      private
+
+      def find_mismatches
+        type_mismatch || (keyset_mismatches + value_mismatches)
+      end
+
+      def type_mismatch
+        expectation = "be a #{expected_class}, but got #{actual.class}"
+        actual.is_a?(expected_class) ?
+          nil :
+          [Mismatch.new(actual, expected_class, [], expectation)]
+      end
+
+      def expected_class
+        raise NotImplementedError.new "#{self.class.name} must implement expected_class"
+      end
+
+      def value_mismatches
+        matching_keys.flat_map do |key|
+          comparison = fetch(key, expected).compare(fetch(key, actual))
+
+          comparison.mismatches.map do |mismatch|
+            Mismatch.at key, mismatch
+          end
+        end
+      end
+
+      def keyset_mismatches
+        if extra_keys.empty? && missing_keys.empty?
+          []
+        else
+          missing_keys_expectation = missing_keys.any? ?
+            "\nmissing keys were:\n\t#{missing_keys.map(&:inspect).join("\n\t")}" :
+            ''
+
+          extra_keys_expectation = extra_keys.any? ?
+            "\nextra keys were:\n\t#{extra_keys.map(&:inspect).join("\n\t")}" :
+            ''
+
+          expectation = "have a different set of keys" +
+            missing_keys_expectation +
+            extra_keys_expectation
+
+          [Mismatch.new(actual, expected, [], expectation)]
+        end
+      end
+
+      def extra_keys
+        raise NotImplementedError.new "#{self.class.name} must implement extra_keys"
+      end
+
+      def missing_keys
+        raise NotImplementedError.new "#{self.class.name} must implement missing_keys"
+      end
+
+      def matching_keys
+        raise NotImplementedError.new "#{self.class.name} must implement matching_keys"
+      end
+
+      def fetch(key, from_map)
+        raise NotImplementedError.new "#{self.class.name} must implement fetch"
+      end
+    end
+  end
+
+  class Hash < Schema
+    class Comparison < Hashema::Map::Comparison
+
+      private
+
+      def expected_class
+        ::Hash
+      end
+
+      def extra_keys
+        @extra_keys ||= actual_keys - expected_keys
+      end
+
+      def missing_keys
+        @missing_keys ||= expected_keys - actual_keys
+      end
+
+      def matching_keys
+        @matching_keys ||= expected.keys & actual.keys
+      end
+
+      def fetch(key, hash)
+        hash[key]
+      end
+
+      def expected_keys
+        @expected_keys ||= Set.new(expected.keys)
+      end
+
+      def actual_keys
+        @actual_keys ||= Set.new(actual.keys)
+      end
+    end
+  end
+
+  class Alternatives < Schema
+    def initialize(*args)
+      super(args)
+    end
+
+    class Comparison < Hashema::Comparison
+
+      private
+
+      def find_mismatches
+        if expected.none? { |alternative| alternative.compare(actual).match? }
+          [Mismatch.new(actual, expected, [])]
+        else
+          []
+        end
+      end
+    end
+  end
+
+  class HashWithIndifferentAccess < Schema
+    class Comparison < Hashema::Map::Comparison
+
+      private
+
+      def expected_class
+        ::Hash
+      end
+
+      def extra_keys
+        @extra_keys ||= actual.keys.reject do |key|
+          expected.has_key? symbol_to_string key or
+            expected.has_key? string_to_symbol key
+        end
+      end
+
+      def missing_keys
+        @missing_keys ||= expected.keys.reject do |key|
+          actual.has_key? symbol_to_string key or
+            actual.has_key? string_to_symbol key
+        end
+      end
+
+      def matching_keys
+        @matching_keys ||=
+          Set.new(expected.keys.map(&method(:symbol_to_string))) &
+          Set.new(actual.keys.map(&method(:symbol_to_string)))
+      end
+
+      def fetch(key, hash)
+        return hash[symbol_to_string key] if hash.has_key? symbol_to_string key
+        return hash[string_to_symbol key] if hash.has_key? string_to_symbol key
+      end
+
+      def string_to_symbol(key)
+        key.is_a?(String) ? key.to_sym : key
+      end
+
+      def symbol_to_string(key)
+        key.is_a?(Symbol) ? key.to_s : key
+      end
+
+      def expected_keys
+        @expected_keys ||= Set.new(expected.keys.map(&method(:symbol_to_string)))
+      end
+
+      def actual_keys
+        @actual_keys ||= Set.new(actual.keys.map(&method(:symbol_to_string)))
+      end
+    end
+  end
+
+  class Mismatch < Struct.new(:actual, :expected, :location, :verb)
+    def self.at(location, original)
+      new original.actual,
+          original.expected,
+          [location] + original.location
+    end
+
+    def message
+      "expected /#{location.join '/'} to #{verb}"
+    end
+
+    private
+
+    def verb
+      super || "match\n\t#{expected.inspect}\nbut got\n\t#{actual.inspect}"
+    end
+  end
+end

data/lib/hashema/validator.rb

@@ -1,120 +1,29 @@
+require_relative './compiler'
+
 module Hashema
   class Validator
-    def initialize(actual, schema)
+    def initialize(actual, schema, options={})
       @actual = actual
       @schema = schema
-      @withholding_judgement = false
-      match! @actual, @schema
+      @schema = compile schema, options
     end
 
     def valid?
-      !!@match
+      comparison.match?
     end
 
     def failure_message
-      @mismatch
+      comparison.mismatches[0].message
     end
 
     private
 
-    def match!(actual, schema, path=[])
-      @match = begin
-        if schema.is_a? Hash
-          match_hash! actual, schema, path
-        elsif schema.is_a? Array and schema.length == 1
-          match_array! actual, schema, path
-        elsif schema.is_a? Array and schema.length > 1
-          match_alternatives! actual, schema, path
-        else
-          match_with_triple_equals! actual, schema, path
-        end
-      end
-    end
-
-    def match_hash!(actual, schema, path)
-      if actual.is_a? Hash
-        if schema.keys.sort == actual.keys.sort
-          match_hash_with_same_keys! actual, schema, path
-        else
-          report_mismatched_key_sets! actual, schema, path
-        end
-      else
-        report_error "expected #{format_path path} to be a Hash, but got #{actual.class}"
-        false
-      end
-    end
-
-    def match_hash_with_same_keys!(actual, schema, path)
-      recording_mismatches actual, schema, path do
-        actual.all? do |key, value|
-          match! value, schema[key], path + [key]
-        end
-      end
-    end
-
-    def report_mismatched_key_sets!(actual, schema, path)
-      extras = actual.keys - schema.keys
-      missing = schema.keys - actual.keys
-      error = "expected #{format_path path} to have a different set of keys\n"
-      error += "the extra keys were:\n  #{extras.map(&:inspect).join("\n  ")}\n" if extras.any?
-      error += "the missing keys were:\n  #{missing.map(&:inspect).join("\n  ")}\n" if missing.any?
-      report_error error
-      false
-    end
-
-    def match_array!(actual, schema, path)
-      if actual.is_a? Array
-        recording_mismatches actual, schema, path do
-          actual.is_a? Array and
-          actual.each_with_index.all? { |elem, i| match! elem, schema[0], path + [i] }
-        end
-      else
-        report_error "expected #{format_path path} to be an Array, but got #{actual.class}"
-        false
-      end
-    end
-
-    def match_alternatives!(actual, alternatives, path)
-      recording_mismatches actual, alternatives, path do
-        alternatives.any? do |alternative|
-          withholding_judgement actual, alternatives, path do
-            match! actual, alternative, path
-          end
-        end
-      end
-    end
-
-    def match_with_triple_equals!(actual, expected, path)
-      recording_mismatches actual, expected, path do
-        expected === actual
-      end
-    end
-
-    def withholding_judgement(actual, schema, path)
-      original_withholding_judgement = @withholding_judgement
-      @withholding_judgement = true
-      returned = yield
-      @withholding_judgement = original_withholding_judgement
-      returned
-    end
-
-    def recording_mismatches(actual, schema, path)
-      if yield
-        true
-      else
-        report_error "expected #{format_path path} to match\n#{schema.inspect}\nbut got\n#{actual.inspect}"
-        false
-      end
-    end
-
-    def report_error(error)
-      unless @withholding_judgement
-        @mismatch ||= error
-      end
+    def compile(schema, options={})
+      Hashema::Compiler.compile(schema, options)
     end
 
-    def format_path(path)
-      "/#{path.join("/")}"
+    def comparison
+      @comparison ||= @schema.compare(@actual)
     end
   end
 end

data/lib/hashema/version.rb

@@ -1,5 +1,5 @@
 module Hashema
   module Version
-    STRING = '0.0.2'
+    STRING = '0.1.0'
   end
 end

metadata

@@ -1,27 +1,30 @@
 --- !ruby/object:Gem::Specification
 name: hashema
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
+  prerelease: 
 platform: ruby
 authors:
 - Ben Christel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-22 00:00:00.000000000 Z
+date: 2015-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: 2.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: 2.0.0
 description: Assert that JSONable objects conform to a schema
@@ -32,7 +35,9 @@ extra_rdoc_files:
 - README.md
 files:
 - lib/hashema.rb
+- lib/hashema/compiler.rb
 - lib/hashema/conform_to_schema.rb
+- lib/hashema/schema.rb
 - lib/hashema/validator.rb
 - lib/hashema/version.rb
 - License.txt
@@ -40,27 +45,27 @@ files:
 homepage: http://github.com/benchristel/hashema
 licenses:
 - MIT
-metadata: {}
 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
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - '>='
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.0
+rubygems_version: 1.8.23
 signing_key: 
-specification_version: 4
-summary: hashema-0.0.2
+specification_version: 3
+summary: hashema-0.1.0
 test_files: []
-has_rdoc: 

checksums.yaml

@@ -1,7 +0,0 @@
----
-SHA1:
-  metadata.gz: 0320697b5755730fd8ffa18843b0f3b496cfd739
-  data.tar.gz: 8bf8bcedb3d51e880d5a13c499754c3fc604a5c0
-SHA512:
-  metadata.gz: f8e5882479f1cbb3a9923575812eafc7d78281a69fd070f6ac488468e4b9d002ccfaca37b41717522df1d8429a2559251b07c321941f09a388f99a28aaafda12
-  data.tar.gz: 98a5238131421fb6fe61ff625cf2cbd71ffaaada4d2280df5079f25540709aa0e6cdb872336eb05a229d6819116ff2d894ffe3640cb5db1a03b7c35c5d154a7b