structured_reader 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0621752b200561ae03415cd92ccbd8a9c65db9ff
-  data.tar.gz: c7af4b1c0273c3e44b87efc782eec2235a8bff21
+  metadata.gz: fc24067c752c75359adf7819eb53548cabe39037
+  data.tar.gz: 468e6deb0c0326c0ac431c9d77a63d40bc366b81
 SHA512:
-  metadata.gz: 522146b8e92418a53a6047b675a4b1306f2d3b14a0fc8054f137051ca931080acbbb8c266de3e8e05271c06bdff8e8e5c9521dbe703ac3c7b8fe248df679a48c
-  data.tar.gz: 6750388513520282561be86f6779f2c74a08a4b7a226b1c473d179b893a4d061256a87f4f00728e7e6a6b777fe621fa3743177383ea5cb6a1d6f6b9c958a4b3c
+  metadata.gz: d44c39fb69b8f9b9f29f361eb2df44bbb5d74e355f847edca948c6dfed19034b5d2812573652baec4baebe0617b70e619ec562fc1722e9fca834cead1b6d8885
+  data.tar.gz: d6738272399d1f8716573644969fe58d932fa5c657253b76cfb6b01fcb8f74699ccbe4c356d6dee38ab84bf78f8d27397700b7dabe4599fd42cb73c137eb53a3

data/CHANGES.md

@@ -0,0 +1,7 @@
+## 1.0.1 (2017-12-26)
+
+* Add a full validation reading mode that reports every detected error with the document.
+
+## 1.0.0 (2017-12-24)
+
+* First release!

data/README.md

@@ -1,6 +1,6 @@
 # StructuredReader
 
-[![Build Status](https://travis-ci.org/mboeh/structured_reader.svg?branch=master)](https://travis-ci.org/mboeh/structured_reader)
+[![Build Status](https://travis-ci.org/mboeh/structured_reader.svg?branch=master)](https://travis-ci.org/mboeh/structured_reader) [![Gem Version](https://badge.fury.io/rb/structured_reader.svg)](https://badge.fury.io/rb/structured_reader)
 
 This library allows you to create declarative rulesets (or schemas) for reading primitive data structures (hashes + arrays + strings + numbers) or JSON into validated data objects. Free yourself from `json.fetch(:widget).fetch(:box).fetch(:dimensions).fetch(:width)`. Get that good `widget.box.dimensions.width` without risking NoMethodErrors. Have confidence that if you're passed total unexpected nonsense, it won't be smoothed over by a convenient MagicHashyMash.
 
@@ -91,6 +91,34 @@ p result.widgets[1].last_updated_at # ==> #<DateTime: 2017-12-24T01:05:00-08:00
 p result.widgets[1].comment # ! ==> NoMethodError
 ```
 
+## Validation
+
+Readers validate input to ensure it is of the expected type:
+
+```ruby
+reader = StructuredReader.json do |o|
+  o.object :point do |pt|
+    pt.number :x
+    pt.number :y
+  end
+end
+
+reader.read({}) # ! ==> StructuredReader::WrongTypeError: expected a Hash, got a NilClass (at .point)
+reader.read({point: {} }) # ! ==> StructuredReader::WrongTypeError: expected a Numeric, got a NilClass (at .point.x)
+reader.read({point: { x: 1, y: "f" } }) # ! ==> StructuredReader::WrongTypeError: expected a Numeric, got a String (at .point.y)
+```
+
+A full validation mode is also available, which avoids exceptions:
+
+```ruby
+r = reader.validate({point: { x: nil, y: "f" } })
+p r.ok? # ==> false
+p r.errors # ==> [[".point.x", "expected a Numeric"], [".point.y", "expected a Numeric"]
+
+r2 = reader.validate({point: { x: 5, y: 10 }})
+p r2.object.point.x # ==> 5
+```
+
 ## Reader Types
 
 * `string`: The classic.

data/examples/exceptions.rb

@@ -0,0 +1,54 @@
+require 'bundler/setup'
+
+require 'structured_reader'
+
+reader = StructuredReader.json do |o|
+  o.collection :widgets do |w|
+    w.string :type, "widgetType"
+    w.number :price
+    w.string :description, nullable: true
+    w.array :tags, of: :string
+    w.object :dimensions, nullable: true do |dims|
+      dims.number :weight
+      dims.number :width
+      dims.number :height
+    end
+    w.time :last_updated_at, "lastUpdated"
+  end
+  o.object :pagination do |pg|
+    pg.string :next_url, "nextUrl", nullable: true
+    pg.number :total_items, "totalItems"
+  end
+end
+
+document = {
+  widgets: [
+    {
+      widgetType: "squorzit",
+      price: 99.99,
+      description: "who can even say?",
+      tags: ["mysterious", "magical"],
+      dimensions: {
+        weight: 10,
+        width: 5,
+        height: nil
+      },
+      lastUpdated: "2017-12-24 01:01 AM PST"
+    },
+    {
+      widgetType: "frobulator",
+      price: "0.79",
+      tags: [123, { foo: "bar" }],
+      lastUpdated: nil
+    }
+  ],
+  pagination: {
+    nextUrl: nil,
+    totalItems: 2
+  }
+}
+
+result = reader.validate(document)
+
+p result.ok?
+p result.errors

data/lib/structured_reader.rb

@@ -27,7 +27,13 @@ module StructuredReader
       if document.kind_of?(String)
         document = JSON.parse document
       end
-      @root_reader.read(document, context)
+      context.open do
+        @root_reader.read(document, context)
+      end
+    end
+
+    def validate(document)
+      read(document, ValidatorContext.new)
     end
 
     class ObjectReader
@@ -283,8 +289,11 @@ module StructuredReader
 
       def read(fragment, context)
         @readers.each do |reader|
-          if reader.read(fragment, ValidatorContext.new).empty?
-            return context.accept(reader.read(fragment, context))
+          result = ValidatorContext.new.open do |context|
+            reader.read(fragment, context)
+          end
+          if result.ok?
+            return context.accept(result.object)
           end
         end
 
@@ -320,6 +329,10 @@ module StructuredReader
         fragment
       end
 
+      def open(&blk)
+        blk.call(self)
+      end
+
       def flunk(fragment, reason)
         raise WrongTypeError, "#{reason}, got a #{fragment.class} (at #{@where})"
       end
@@ -331,14 +344,24 @@ module StructuredReader
     end
 
     class ValidatorContext
+      Result = Struct.new(:object, :errors) do
+        def ok?
+          errors.empty?
+        end
+      end
 
       def initialize(where = "", errors = [])
         @where = where.dup.freeze
         @errors = errors
       end
 
+      def open(&blk)
+        result = blk.call(self)
+        Result.new(@errors.any? ? nil : result, @errors)
+      end
+
       def accept(fragment)
-        @errors
+        fragment
       end
 
       def flunk(fragment, reason)

data/lib/structured_reader/version.rb

@@ -1,3 +1,3 @@
 module StructuredReader
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: structured_reader
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Matthew Boeh
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-12-25 00:00:00.000000000 Z
+date: 2018-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -64,6 +64,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- CHANGES.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -71,6 +72,7 @@ files:
 - bin/console
 - bin/setup
 - examples/example.rb
+- examples/exceptions.rb
 - examples/selection.rb
 - examples/union.rb
 - lib/structured_reader.rb