rschema_hamster 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d51cbfa9644a3a7c41cddbda5e9487687cb7e550
-  data.tar.gz: 9447762eb704849daa902bd3fd7dabad102bc04f
+  metadata.gz: 02922c410a8a09d62e7ab3b3484d262dbd1aa020
+  data.tar.gz: 1ff95e47d3a34bb1442770a815837615ff3fa32e
 SHA512:
-  metadata.gz: 2622279af6818f76227d8654414bef9a1dd69dfd9081525617398792a6a14b3ead95330c8af3d66db17fa8b852dc575b70c8a4d01a286e30c115a1f7ad0706b6
-  data.tar.gz: c21f7acd1cfb2c2583efebd81fa11ccef567da0fa92146a754a851c72a0d95eb9c9d114efc908550c7fb4b30d0550fc08bbca899123836206f68f31db3dc0c6f
+  metadata.gz: df924a013064ef6c5e6035959d51facb4e558215aef5b01d8fb796524a06308b9313bc1507902d41772d8ef49368fa077a3983574f12025a5c1a4c130b945171
+  data.tar.gz: 98663647b0b6e0947ad26de724ad2ba504532bfed980772946ad8e618a9e877f2b5efb1d79b0fdc048f3483f2025e8a64aef43cdbe7e124dcdb6e60ce773eead

data/Readme.md

@@ -1,51 +1,137 @@
 # RSchema-Hamster
 
-Extends [RSchema][RSCHEMA-DOC] to support [Hamster's][HAMSTER-DOC] immutable Hash, Vector, List and Set structures.
+Use schemas to define the shape of your immutable data structures.  Combines the declarative data-driven schemas from [RSchema][RSCHEMA-DOC] with the persistent collections from [Hamster][HAMSTER-DOC].
 
-```ruby
-Email = String
-PostalCode = String
+### Baseline
 
-Person = Hamster.hash(
-  name: String,
-  email: Email
-)
+Peek at the examples in this Readme, but head over to RSchema's docs for a much better intro to using Ruby data to define and validate data structures... RSchema-Hamster merely extends RSchema by bringing Hamster's classes into the fold, and you can still mix-and-match Ruby's built-in collections as well as RSchema's DSL for generic and optional values. Likewise, see Hamster's docs for an intro to immutable structures in Ruby.
+
+[![Build Status](https://travis-ci.org/dcrosby42/rschema_hamster.svg?branch=master)](https://travis-ci.org/dcrosby42/rschema_hamster)
+
+## What this gem adds
+
+### Hamster::Hash as a schema
+Hamster's immutable Hash structures may be used as schemas, and will be validated using the same algorithm RSchema uses to evaluate Ruby's built-in Hash, with the additional requirement that values are, in fact, Hamster::Hashes.
 
+*Example*:
+```ruby
 Address = Hamster.hash(
   street: String,
-  postal_code: PostalCode
+  postal_code: Integer
 )
 
-Contact = Hamster.hash(
-  person: Person,
-  addresses: Hamster.vector(Address)
-)
+RSchema.validate!(Address, Hamster.hash(street: "187 Drury Ln", postal_code: 1234))
+```
 
-ContactList = Hamster.vector(Contact)
+### Generic Hashes: consistent key/value types
+Use RSchemaHamster::DSL.hamster_hash_of(s1 => s2) to describe a variable-sized Hash whose keys all conform to s1 and whose values conform to s2.
+
+*Example*:
+```ruby
+PlayerScores = RSchemaHanster.schema {
+  hamster_hash_of(String => Integer)
+}
+
+RSchema.validate!(PlayerScores, Hamster.hash("Link" => 12, "Samus" => 132))
 ```
 
-DONE:
+### Hamster::Vector as a schema
+Hamster's immutable Vector structures may be used as schemas, and will be validated using the same rules and alternatives RSchema uses to evaluate Ruby's built-in Array, with the additional requirement that values are, in fact, Hamster::Vectors.
+
+Vectors with length > 1 are interprested as tuples, validating Vectors of same length whose nth element validates according to the nth subschema.
 
-* Hamster::Vector
-* Hamster::Hash - known keys
-* Hamster::List 
-* Test DSL:
-** _?
-** maybe
-** hamster_hash_of
-** hamster_set_of - Hasmter::Set -(GenericHamsterSetSchema)
-** enum
+```ruby
+Token = Hamster.vector(Symbol, String)
+
+RSchema.validate!(Token, Hamster.vector(:keyword, "require"))
+```
 
-TODO:
+Single-length Vectors validates a 0-or-more-length Vector whose elements validate according to the single subschema.  
+
+```ruby
+Tokens = Hamster.vector(Token)
+
+RSchema.validate!(Tokens, Hamster.vector(
+  Hamster.vector(:keyword, "require"),
+  Hamster.vector(:quot, "'"),
+  Hamster.vector(:string_lit, "rschema_hamster"),
+  Hamster.vector(:quot, "'")
+))
+```
 
-Project:
-* Proper readme
-* .gem
 
-Implement someday:
+### Hamster::List as a schema
+(Actually Hamster::Cons) currently implemented in parallel to Hamster::Vector.  Consider making this a "lazy validated" schema?
 
-* Structs
-* Hamsterdam::Struct
+### Sets
+
+```ruby
+Words = RSchemaHamster.schema {
+  hamster_set_of(String)
+}
+RSchema.validate!(TheSyms, Hamster.set("some", "of", "words"))
+```
+
+## Example:
+
+The schema:
+
+```ruby
+module OrderReport::Schema
+  Name    = String
+  Id      = Integer
+  Dollars = BigDecimal
+
+  Totals = Hamster.hash(
+    gross: Dollars,
+    tax:   Dollars,
+    fee:   Dollars,
+    net:   Dollars,
+  )
+
+  OrderRow = Hamster.hash(
+    order_id:     Id,
+    order_number: Name,
+    order_totals: Totals,
+  )
+
+  MarketBlock = Hamster.hash(
+    market_id:        Id,
+    market_name:      Name,
+    account_dropdown: RSchemaHamster.schema {
+      hamster_hash_of(Name => Id)
+    },
+    order_rows:       Hamster.vector(OrderRow),
+    market_totals:    Totals
+  )
+end
+```
+
+The data (Hamster.from is a convenience that recursively converts Hash and Array to Hamster::Hash and Hamster::Vector):
+```ruby
+def self.dollars(str); BigDecimal.new(str); end
+
+market_block = Hamster.from(  
+  { 
+    market_id: 42,
+    market_name: "The Restaurant at the End of the Universe",
+    account_dropdown: {
+      "Hotblack Desiato" => 1, 
+      "Zaphod Beeblebrox" => 3
+    },
+    order_rows: [
+      { order_id: 101, order_number: "MILLIWAYS-00101", order_totals: { gross: dollars("120"), tax: dollars("14.4"), fee: dollars("20"), net: dollars("85.6") } },
+      { order_id: 102, order_number: "MILLIWAYS-00102", order_totals: { gross: dollars("3030"), tax: dollars("363.6"), fee: dollars("505.10"), net: dollars("2161.3") } },
+    ],
+    market_totals: { gross: dollars("3150"), tax: dollars("378"), fee: dollars("525.10"), net: dollars("2246.9") }
+  }
+) 
+```
+
+The validation:
+```ruby
+RSchema.validate!(OrderReport::HamsterSchema::MarketBlock, market_block)
+```
 
 [HAMSTER-DOC]: https://github.com/hamstergem/hamster 
 [RSCHEMA-DOC]: https://github.com/tomdalling/rschema

data/lib/rschema_hamster.rb

@@ -1,99 +1,10 @@
 require 'rschema'
 require 'hamster'
+require 'rschema_hamster/hamster_ext'
 require 'rschema_hamster/dsl'
 
-class Hamster::Vector
-  def schema_walk(value, mapper)
-    fixed_size = (self.size != 1)
-
-    if not value.is_a?(Hamster::Vector)
-      RSchema::ErrorDetails.new(value, 'is not a Hamster::Vector')
-    elsif fixed_size && value.size != self.size
-      RSchema::ErrorDetails.new(value, "does not have #{self.size} elements")
-    else
-      value.map.with_index do |subvalue, idx|
-        subschema = (fixed_size ? self[idx] : first)
-        subvalue_walked, error = RSchema.walk(subschema, subvalue, mapper)
-        break error.extend_key_path(idx) if error
-        subvalue_walked
-      end
-    end
-  end
-end
-
-class Hamster::Cons
-  def schema_walk(value, mapper)
-    fixed_size = (self.size != 1)
-
-    if value == Hamster::EmptyList and !fixed_size
-      value
-    elsif not value.is_a?(Hamster::Cons)
-      RSchema::ErrorDetails.new(value, 'is not a Hamster List')
-    elsif fixed_size && value.size != self.size
-      RSchema::ErrorDetails.new(value, "does not have #{self.size} elements")
-    else
-      result = Hamster.list
-      failure = nil
-      value.each.with_index do |subvalue, idx|
-        subschema = (fixed_size ? self[idx] : first)
-        subvalue_walked, error = RSchema.walk(subschema, subvalue, mapper)
-        if error 
-          error.extend_key_path(idx)
-          failure = error
-          break
-        else
-          result = result.cons(subvalue_walked)
-        end
-      end
-      return (failure or result.reverse)
-
-    end
-  end
-end
-
-class Hamster::Hash
-  def schema_walk(value, mapper)
-    return RSchema::ErrorDetails.new(value, 'is not a Hash') if not value.is_a?(Hamster::Hash)
-
-    # extract details from the schema
-    required_keys = Set.new
-    all_subschemas = {}
-    each do |(k, subschema)|
-      if k.is_a?(RSchema::OptionalHashKey)
-        all_subschemas[k.key] = subschema
-      else
-        required_keys << k
-        all_subschemas[k] = subschema
-      end
-    end
-
-    # check for extra keys that shouldn't be there
-    extraneous = value.keys.reject{ |k| all_subschemas.has_key?(k) }
-    if extraneous.size > 0
-      return RSchema::ErrorDetails.new(value, "has extraneous keys: #{extraneous.to_a.inspect}")
-    end
-
-    # check for required keys that are missing
-    missing_requireds = required_keys.reject{ |k| value.has_key?(k) }
-    if missing_requireds.size > 0
-      return RSchema::ErrorDetails.new(value, "is missing required keys: #{missing_requireds.to_a.inspect}")
-    end
-
-    # walk the subvalues
-    value.reduce(Hamster.hash) do |accum, (k, subvalue)|
-      # puts "RSchema.walk(all_subschemas[k], subvalue, mapper) all_subschemas[#{k.inspect}]: #{all_subschemas[k].inspect}, subvalue: (#{subvalue.class}) #{subvalue.inspect}"
-      subvalue_walked, error = RSchema.walk(all_subschemas[k], subvalue, mapper)
-      # puts "  => subvalue_walked: (#{subvalue_walked.class}) #{subvalue_walked.inspect}, error: #{error.inspect}"
-      break error.extend_key_path(k) if error
-      a = accum.put(k, subvalue_walked)
-      # puts "  (accum: #{accum.inspect})"
-      a
-    end
-  end
-end
-
-module RSchema
-  module DSL
-    extend RSchemaHamster::DSL
+module RSchemaHamster
+  def self.schema(dsl=RSchemaHamster::DSL, &block)
+    RSchema.schema(dsl, &block)
   end
 end

data/lib/rschema_hamster/dsl.rb

@@ -1,15 +1,19 @@
 module RSchemaHamster
   module DSL
-    def hamster_hash_of(subschemas_hash)
-      raise InvalidSchemaError unless subschemas_hash.size == 1
-      GenericHamsterHashSchema.new(
-        subschemas_hash.keys.first, 
-        subschemas_hash.values.first)
-    end
+    module Base
+      def hamster_hash_of(subschemas_hash)
+        raise InvalidSchemaError unless subschemas_hash.size == 1
+        GenericHamsterHashSchema.new(
+          subschemas_hash.keys.first, 
+          subschemas_hash.values.first)
+      end
 
-    def hamster_set_of(subschema)
-      GenericHamsterSetSchema.new(subschema)
+      def hamster_set_of(subschema)
+        GenericHamsterSetSchema.new(subschema)
+      end
     end
+    extend Base
+    extend RSchema::DSL::Base # bring along RSchema's maybe, hash_of, set_of etc.
   end
   
   GenericHamsterHashSchema = Struct.new(:key_subschema, :value_subschema) do

data/lib/rschema_hamster/extend_rschema_dsl.rb

@@ -0,0 +1,13 @@
+require 'rschema_hamster'
+
+# 'require' this file to extend RSchema's DSL with RSchema-Hamster's own DSL methods.
+# Provides more convenient access to the full set of DSL methods (hash_of AND hamster_hash_of, etc.) by typing 
+#   RSchema.schema { ... } 
+# instead of
+#   RSchema.schema(RSchemaHamster::DSL) { ... }
+# ...at the expense of monkey-patching RSchema's DSL module, which shouldn't really cause problems, but would be rude to presume on.
+module RSchema
+  module DSL
+    extend RSchemaHamster::DSL::Base
+  end
+end

data/lib/rschema_hamster/hamster_ext.rb

@@ -0,0 +1,89 @@
+class Hamster::Vector
+  def schema_walk(value, mapper)
+    fixed_size = (self.size != 1)
+
+    if not value.is_a?(Hamster::Vector)
+      RSchema::ErrorDetails.new(value, 'is not a Hamster::Vector')
+    elsif fixed_size && value.size != self.size
+      RSchema::ErrorDetails.new(value, "does not have #{self.size} elements")
+    else
+      value.map.with_index do |subvalue, idx|
+        subschema = (fixed_size ? self[idx] : first)
+        subvalue_walked, error = RSchema.walk(subschema, subvalue, mapper)
+        break error.extend_key_path(idx) if error
+        subvalue_walked
+      end
+    end
+  end
+end
+
+class Hamster::Cons
+  def schema_walk(value, mapper)
+    fixed_size = (self.size != 1)
+
+    if value == Hamster::EmptyList and !fixed_size
+      value
+    elsif not value.is_a?(Hamster::Cons)
+      RSchema::ErrorDetails.new(value, 'is not a Hamster List')
+    elsif fixed_size && value.size != self.size
+      RSchema::ErrorDetails.new(value, "does not have #{self.size} elements")
+    else
+      result = Hamster.list
+      failure = nil
+      value.each.with_index do |subvalue, idx|
+        subschema = (fixed_size ? self[idx] : first)
+        subvalue_walked, error = RSchema.walk(subschema, subvalue, mapper)
+        if error 
+          error.extend_key_path(idx)
+          failure = error
+          break
+        else
+          result = result.cons(subvalue_walked)
+        end
+      end
+      return (failure or result.reverse)
+
+    end
+  end
+end
+
+class Hamster::Hash
+  def schema_walk(value, mapper)
+    return RSchema::ErrorDetails.new(value, 'is not a Hash') if not value.is_a?(Hamster::Hash)
+
+    # extract details from the schema
+    required_keys = Set.new
+    all_subschemas = {}
+    each do |(k, subschema)|
+      if k.is_a?(RSchema::OptionalHashKey)
+        all_subschemas[k.key] = subschema
+      else
+        required_keys << k
+        all_subschemas[k] = subschema
+      end
+    end
+
+    # check for extra keys that shouldn't be there
+    extraneous = value.keys.reject{ |k| all_subschemas.has_key?(k) }
+    if extraneous.size > 0
+      return RSchema::ErrorDetails.new(value, "has extraneous keys: #{extraneous.to_a.inspect}")
+    end
+
+    # check for required keys that are missing
+    missing_requireds = required_keys.reject{ |k| value.has_key?(k) }
+    if missing_requireds.size > 0
+      return RSchema::ErrorDetails.new(value, "is missing required keys: #{missing_requireds.to_a.inspect}")
+    end
+
+    # walk the subvalues
+    value.reduce(Hamster.hash) do |accum, (k, subvalue)|
+      # puts "RSchema.walk(all_subschemas[k], subvalue, mapper) all_subschemas[#{k.inspect}]: #{all_subschemas[k].inspect}, subvalue: (#{subvalue.class}) #{subvalue.inspect}"
+      subvalue_walked, error = RSchema.walk(all_subschemas[k], subvalue, mapper)
+      # puts "  => subvalue_walked: (#{subvalue_walked.class}) #{subvalue_walked.inspect}, error: #{error.inspect}"
+      break error.extend_key_path(k) if error
+      a = accum.put(k, subvalue_walked)
+      # puts "  (accum: #{accum.inspect})"
+      a
+    end
+  end
+end

data/lib/rschema_hamster/version.rb

@@ -1,3 +1,3 @@
 module RSchemaHamster
-  VERSION = '0.0.2'
+  VERSION = '0.1.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rschema_hamster
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - David Crosby
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-03 00:00:00.000000000 Z
+date: 2015-06-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hamster
@@ -67,7 +67,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '10'
 - !ruby/object:Gem::Dependency
-  name: awesom_print
+  name: awesome_print
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -108,8 +108,10 @@ files:
 - Readme.md
 - lib/rschema_hamster.rb
 - lib/rschema_hamster/dsl.rb
+- lib/rschema_hamster/extend_rschema_dsl.rb
+- lib/rschema_hamster/hamster_ext.rb
 - lib/rschema_hamster/version.rb
-homepage: https://github.com/dcrosby42
+homepage: https://github.com/dcrosby42/rschema_hamster
 licenses:
 - MIT
 metadata: {}