rschema 3.0.1.pre5 → 3.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2e570ef90c1907cc057e0b5edf7cd2bac22ace47
-  data.tar.gz: 05039b6e5b72eea3f86b0fa1295f61055dab7a16
+  metadata.gz: e971b0b2b3d6a20e7d3a4d30c0426ea3f58e02f7
+  data.tar.gz: a1cacce7540b7a25698c48e5aa1f57847dc55a85
 SHA512:
-  metadata.gz: 111ad7ee2f51e27bd18636566d108d5313367ea77c1ffcc11db890db571e1887712af9fab9d35d7a27e57bb6cb314f3358f662e8322d0bc849e05f3c4e61a9d9
-  data.tar.gz: 2434658702e5ea3b87ba91cea91868d01f30bdcee10a430cf3fc3a5669f4126167cf7fc2a7f971c53136cdfdb59d749441e375ebf9d2145a4ce76e988eb54851
+  metadata.gz: 05194c41bc61d36b6ebacc94583ab20fa693e8ad3d3cd69858fcdcd3ac110b73e5953180f8fbc9f5f18b3fa9099f210c925136feb08a90cf27efa4c28463e17f
+  data.tar.gz: 2f446b9473c06e7ad75ee426a872ec6843271a86b594d87dc07a282b50b51878ac8cbd9ec512cf1a010c55a0d36faf64c517506ea83ba21c7deb17edd9893fd9

data/README.md

@@ -22,7 +22,7 @@ First you create a schema:
 
     blog_post_schema = RSchema.define_hash {{
       title: _String,
-      tags: Array(_Symbol),
+      tags: array(_Symbol),
       body: _String,
     }}
 
@@ -33,59 +33,58 @@ Then you can use the schema to validate data:
       tags: [:trick, :developers, :unbeleivable],
       body: '<p>blah blah</p>'
     }
-    blog_post_schema.call(input).valid? #=> true
+    blog_post_schema.valid?(input) #=> true
 
 What Is A Schema?
 -----------------
 
 Schemas are objects that _describe and validate a value_.
 
-The simplest schemas are `Type` schemas, which just validate the type of a value.
+The simplest schemas are `Type` schemas, which just check the type of a value.
 
     schema = RSchema.define { _Integer }
     schema.class #=> RSchema::Schemas::Type
 
-    schema.call(1234).valid? #=> true
-    schema.call('hi').valid? #=> false
+    schema.valid?(1234) #=> true
+    schema.valid?('hi') #=> false
 
 Then there are composite schemas, which are schemas composed of subschemas.
 
-Arrays are composite schemas:
+Array schemas are composite schemas:
 
-    schema = RSchema.define { Array(_Integer) }
-    schema.call([10, 11, 12]).valid?  #=> true
-    schema.call([10, 11, :hi]).valid? #=> false
+    schema = RSchema.define { array(_Integer) }
+    schema.valid?([10, 11, 12])  #=> true
+    schema.valid?([10, 11, :hi]) #=> false
 
-And so are hashes:
+And so are hash schemas:
 
-    schema = RSchema.define do
-      Hash(fname: _String, age: _Integer)
-    end
+    schema = RSchema.define_hash {{
+      fname: _String,
+      age: _Integer,
+    }}
 
-    schema.call({ fname: 'Jane', age: 27 }).valid? #=> true
-    schema.call({ fname: 'Johnny' }).valid? #=> false
+    schema.valid?({ fname: 'Jane', age: 27 }) #=> true
+    schema.valid?({ fname: 'Johnny no age' }) #=> false
 
 Schema objects are composable – they are designed to be combined.
 This allows schemas to describe complex, nested data structures.
 
-    schema = RSchema.define_hash do
-      {
-        fname: predicate { |n| n.is_a?(String) && n.size > 0 },
-        favourite_foods: Set(_Symbol),
-        children_by_age: VariableHash(_Integer => _String)
-      }
-    end
+    schema = RSchema.define_hash {{
+      fname: maybe(_String),
+      favourite_foods: set(_Symbol),
+      children_by_age: variable_hash(_Integer => _String)
+    }}
 
     input = {
-      fname: 'Johnny',
-      favourite_foods: Set.new([:bacon, :cheese, :onion]),
+      fname: nil,
+      favourite_foods: Set[:bacon, :cheese, :onion],
       children_by_age: {
         7 => 'Jenny',
         5 => 'Simon',
       },
     }
 
-    schema.call(input).valid? #=> true
+    schema.valid?(input) #=> true
 
 RSchema provides many different kinds of schema classes for common tasks, but
 you can also write custom schema classes if you need to.
@@ -95,34 +94,35 @@ The DSL
 -------
 
 Schemas are usually created and composed via a DSL using `RSchema.define`.
-They can be created manually, although this is often too verbose.
+Schemas can be created without the DSL, but the DSL is much more succinct.
 
 For example, the following two schemas are identical. `schema1` is created via the
 DSL, and `schema2` is created manually.
 
-    schema1 = RSchema.define { Array(_Symbol) }
+    schema1 = RSchema.define { array(_Symbol) }
 
-    schema2 = RSchema::Schemas::VariableArray.new(
-      RSchema::Schemas::Type.new(Symbol)
+    schema2 = RSchema::Schemas::Convenience.wrap(
+      RSchema::Schemas::VariableLengthArray.new(
+        RSchema::Schemas::Type.new(Symbol)
+      )
     )
 
-You will probably never need to create schemas manually unless you are doing
-something advanced, like writing your own DSL.
+You will probably not need to create schemas manually unless you are doing
+something advanced.
 
-The DSL is designed to be extensible. You can add your own methods to the
-default DSL, or create a separate, custom DSL to suite your needs.
+For a full list of DSL methods, see the API documentation for `RSchema::DSL`.
 
 
-When Validation Fails
----------------------
+Errors (When Validation Fails)
+------------------------------
 
-When data fails validation, it is often important to know exactly _which
+When something fails validation, it is often important to know exactly _which
 values_ were invalid, and _why_. RSchema provides details about every
 failure within a result object.
 
     schema = RSchema.define do
-      Array(
-        Hash(
+      array(
+        fixed_hash(
           name: _String,
           hair: enum([:red, :brown, :blonde, :black])
         )
@@ -136,13 +136,11 @@ failure within a result object.
       { name: 'Chris', hair: :red },
     ]
 
-    result = schema.call(input)
+    result = schema.validate(input)
 
-    result.class #=> RSchema::Result
+    result.class  #=> RSchema::Result
     result.valid? #=> false
-    result.error #=> { 2 => { :hair => #<RSchema::Error> } }
-    result.error[2][:hair].to_s
-      #=> "Error RSchema::Schemas::Enum/not_a_member for value: :blond"
+    result.error  #=> { 2 => { :hair => #<RSchema::Error> } }
 
 The error above says that the value `:blond`, which exists at location
 `input[2][:hair]`, is not a valid enum member. Looking back at the schema, we
@@ -156,13 +154,11 @@ error messages for developers or users.
 
     error.value #=> :blond
     error.symbolic_name #=> :not_a_member
-    error.schema #=> #<RSchema::Schemas::Enum>
-    error.to_s #=> "Error RSchema::Schemas::Enum/not_a_member for value: :blond"
-    error.to_s(:detailed) #=>
-      # Error: not_a_member
-      # Schema: RSchema::Schemas::Enum
-      # Value: :blond
-      # Vars: nil
+    error.schema #=> #<RSchema::Schemas::Enum ...>
+    error.schema.members #=> [:red, :brown, :blonde, :black]
+    error.to_s #=> "RSchema::Schemas::Enum/not_a_member"
+    error.inspect
+      #=> "<RSchema::Error RSchema::Schemas::Enum/not_a_member value=:blond>"
 
 
 Type Schemas
@@ -172,8 +168,8 @@ The most basic kind of schema is a `Type` schema.
 Type schemas validate the class of a value using `is_a?`.
 
     schema = RSchema.define { type(String) }
-    schema.call('hi').valid? #=> true
-    schema.call(1234).valid? #=> false
+    schema.valid?('hi') #=> true
+    schema.valid?(1234) #=> false
 
 Type schemas are so common that the RSchema DSL provides a shorthand way to
 create them, using an underscore prefix:
@@ -186,22 +182,21 @@ Because type schemas use `is_a?`, they handle subclasses, and can also be used
 to check for `include`d modules like `Enumerable`:
 
     schema = RSchema.define { _Enumerable }
-    schema.call([1, 2, 3]).valid? #=> true
-    schema.call({ a: 1, b: 2 }).valid? #=> true
+    schema.valid?([1, 2, 3]) #=> true
+    schema.valid?({ a: 12 }) #=> true
 
 Variable-length Array Schemas
 -----------------------------
 
 There are two types of array schemas.
-The first type are `VariableLengthArray` schemas, where every element in the
-array conforms to a single subschema:
+The first type are `VariableLengthArray` schemas, which check that all elements
+in the array conform to a single subschema:
 
-    schema = RSchema.define { Array(_Symbol) }
-    schema.class #=> RSchema::Schemas::VariableLengthArray
+    schema = RSchema.define { array(_Symbol) }
 
-    schema.call([:a, :b, :c]).valid? #=> true
-    schema.call([:a]).valid? #=> true
-    schema.call([]).valid? #=> true
+    schema.valid?([:a, :b, :c]) #=> true
+    schema.valid?([:a]) #=> true
+    schema.valid?([]) #=> true
 
 Fixed-length Array Schemas
 --------------------------
@@ -209,37 +204,38 @@ Fixed-length Array Schemas
 There are also `FixedLengthArray` schemas, where the array must have a specific
 length, and each element of the array has a separate subschema:
 
-    schema = RSchema.define{ Array(_Integer, _String) }
-    schema.class #=> RSchema::Schemas::FixedLengthArray
+    schema = RSchema.define { array(_Integer, _String) }
 
-    schema.call([10, 'hello']).valid? #=> true
-    schema.call([22, 'world']).valid? #=> true
-    schema.call(['heyoo', 33]).valid? #=> false
+    schema.valid?([10, 'hello']) #=> true
+    schema.valid?(['heyoo', 33]) #=> false
 
 Fixed Hash Schemas
 ------------------
 
 There are also two kinds of hash schemas.
 
-`FixedHash` schemas describes hashes where they keys are known constants:
+`FixedHash` schemas describe hashes where they keys are known constants:
 
     schema = RSchema.define do
-      Hash(name: _String, age: _Integer)
+      fixed_hash(
+        name: _String,
+        age: _Integer,
+      )
     end
 
-    schema.call({ name: 'George', age: 2 }).valid? #=> true
+    schema.valid?({ name: 'George', age: 2 }) #=> true
 
 Elements can be optional:
 
     schema = RSchema.define do
-      Hash(
+      fixed_hash(
         name: _String,
         optional(:age) => _Integer,
       )
     end
 
-    schema.call({ name: 'Lucy', age: 21 }).valid? #=> true
-    schema.call({ name: 'Tom' }).valid? #=> true
+    schema.valid?({ name: 'Lucy', age: 21 }) #=> true
+    schema.valid?({ name: 'Ageless Tommy' }) #=> true
 
 `FixedHash` schemas are common, so the `RSchema.define_hash` method exists
 to make their creation more convenient:
@@ -252,13 +248,13 @@ to make their creation more convenient:
 Variable Hash Schemas
 ---------------------
 
-`VariableHash` schemas are for hashes where the keys are _not_ known constants.
+`VariableHash` schemas are for hashes where the keys are _not_ known ahead of time.
 They contain one subschema for keys, and another subschema for values.
 
-    schema = RSchema.define { VariableHash(_Symbol => _Integer) }
-    schema.call({}).valid? #=> true
-    schema.call({ a: 1 }).valid? #=> true
-    schema.call({ a: 1, b: 2 }).valid? #=> true
+    schema = RSchema.define { variable_hash(_Symbol => _Integer) }
+    schema.valid?({}) #=> true
+    schema.valid?({ a: 1 }) #=> true
+    schema.valid?({ a: 1, b: 2 }) #=> true
 
 Other Schema Types
 ------------------
@@ -266,40 +262,40 @@ Other Schema Types
 RSchema provides a few other schema types through its DSL:
 
     # boolean (only true or false)
-    boolean_schema = RSchema.define { Boolean() }
-    boolean_schema.call(true).valid?  #=> true
-    boolean_schema.call(false).valid? #=> true
-    boolean_schema.call(nil).valid?   #=> false
+    boolean_schema = RSchema.define { boolean }
+    boolean_schema.valid?(true)  #=> true
+    boolean_schema.valid?(false) #=> true
+    boolean_schema.valid?(nil)   #=> false
 
     # anything (literally any value)
     anything_schema = RSchema.define { anything }
-    anything_schema.call('Hi').valid?  #=> true
-    anything_schema.call(true).valid?  #=> true
-    anything_schema.call(1234).valid?  #=> true
-    anything_schema.call(nil).valid?   #=> true
+    anything_schema.valid?('Hi')  #=> true
+    anything_schema.valid?(true)  #=> true
+    anything_schema.valid?(1234)  #=> true
+    anything_schema.valid?(nil)   #=> true
 
     # either (sum types)
     either_schema = RSchema.define { either(_String, _Integer, _Float) }
-    either_schema.call('hi').valid? #=> true
-    either_schema.call(5555).valid? #=> true
-    either_schema.call(77.1).valid? #=> true
+    either_schema.valid?('hi') #=> true
+    either_schema.valid?(5555) #=> true
+    either_schema.valid?(77.2) #=> true
 
     # maybe (allows nil)
     maybe_schema = RSchema.define { maybe(_Integer) }
-    maybe_schema.call(5).valid?   #=> true
-    maybe_schema.call(nil).valid? #=> true
+    maybe_schema.valid?(5)   #=> true
+    maybe_schema.valid?(nil) #=> true
 
     # enum (a set of valid values)
     enum_schema = RSchema.define { enum([:a, :b, :c]) }
-    enum_schema.call(:a).valid? #=> true
-    enum_schema.call(:z).valid? #=> false
+    enum_schema.valid?(:a) #=> true
+    enum_schema.valid?(:z) #=> false
 
     # predicate (block returns true for valid values)
     predicate_schema = RSchema.define do
       predicate { |x| x.even? }
     end
-    predicate_schema.call(4).valid? #=> true
-    predicate_schema.call(5).valid? #=> false
+    predicate_schema.valid?(4) #=> true
+    predicate_schema.valid?(5) #=> false
 
     # pipeline (apply multiple schemas to a single value, in order)
     pipeline_schema = RSchema.define do
@@ -308,46 +304,12 @@ RSchema provides a few other schema types through its DSL:
         predicate { |x| x.positive? },
       )
     end
-    pipeline_schema.call(123).valid? #=> true
-    pipeline_schema.call(5.1).valid? #=> true
-    pipeline_schema.call(-24).valid? #=> false
-
-
-Coercion
---------
-
-Coercers convert invalid data into valid data where possible, according to a
-schema.
-
-Take HTTP params as an example. Web forms often contain database IDs, which
-are integers, but are submitted as strings by the browser. Param hash keys
-are often expected to be `Symbol`s, but are also strings. The `HTTPCoercer`
-can automatically convert these strings into the appropriate type, based on a
-schema.
-
-    # Input keys and values are all strings.
-    input_params = {
-      'whatever_id' => '5',
-      'amount' => '123.45',
-    }
-
-    # The schema expects symbol keys, an integer value, and a float value.
-    param_schema = RSchema.define_hash {{
-      whatever_id: _Integer,
-      amount: _Float,
-    }}
-
-    # The schema is wrapped in a HTTPCoercer.
-    coercer = RSchema::HTTPCoercer.wrap(param_schema)
-
-    # Use the coercer like a normal schema object.
-    result = coercer.call(input_params)
-
-    # The result object contains the coerced value
-    result.valid? #=> true
-    result.value #=> { :whatever_id => 5, :amount => 123.45 }
+    pipeline_schema.valid?(123) #=> true
+    pipeline_schema.valid?(5.1) #=> true
+    pipeline_schema.valid?(-24) #=> false
 
-TODO: explain how to create custom coercers
+For a full list of built-in schema types, see the API documentation for all
+classes in the `RSchema::Schemas` module.
 
 Extending The DSL
 -----------------
@@ -371,26 +333,25 @@ And your methods will be available via `RSchema.define`:
 
     schema = RSchema.define { palendrome }
 
-    schema.call('racecar').valid? #=> true
-    schema.call('ferrari').valid? #=> false
-
-This is the preferred way for other gems to extend RSchema with new kinds
-of schema classes.
+    schema.valid?('racecar') #=> true
+    schema.valid?('ferrari') #=> false
 
+This is the preferred way for you, and other gems, to extend RSchema with new
+DSL methods.
 
 Creating Your Own DSL
 ---------------------
 
-The default DSL is designed to be extended (i.e. modified) by external gems/code.
-If you want a DSL that isn't affected by external factors, you can create one
-yourself.
+The default DSL is designed to be extended (i.e. modified) by you, and
+third-party gems. If you want a DSL that isn't affected by external factors,
+you can create one yourself.
 
-Create a new class, and include `RSchema::DSL` to get all the standard DSL
-methods that come built-in to RSchema. You can define your own custom methods
-on this class.
+Create a new class, and include `RSchema::DSL` if you want have all the
+standard DSL methods that come built-in to RSchema. You can define your own
+custom methods on this class.
 
     class MyCustomDSL
-      include RSchema::DSL
+      include RSchema::DSL # this is optional
 
       def palendrome
         pipeline(
@@ -400,22 +361,76 @@ on this class.
       end
     end
 
-Then simply use `instance_eval` to make use of your custom DSL.
+Then pass an instance of your DSL class into `RSchema.define`:
 
-    schema = MyCustomDSL.new.instance_eval { palendrome }
-    schema.call('racecar').valid? #=> true
+    dsl = MyCustomDSL.new
+    schema = RSchema.define(dsl) { palendrome }
+    schema.valid?('racecar') #=> true
 
-See the implementation of `RSchema.define` for reference.
+Coercion
+--------
 
+Coercers convert invalid data into valid data where possible, according to a
+schema.
+
+Take HTTP params as an example. Web forms often contain database IDs, which
+are integers, but are submitted as strings by the browser. Param hash keys
+are often expected to be `Symbol`s, but are also strings. RSchema can
+automatically convert these strings into the appropriate type, based on a
+schema.
 
-Custom Schema Types
--------------------
+    # Input keys and values are all strings
+    input_params = {
+      'whatever_id' => '5',
+      'amount' => '123.45',
+    }
+
+    # The schema expects symbol keys, an integer value, and a float value
+    schema = RSchema.define_hash {{
+      whatever_id: _Integer,
+      amount: _Float,
+    }}
+
+    # A coercer is created by wrapping the schema
+    coercer = RSchema::CoercionWrapper::RACK_PARAMS.wrap(schema)
+
+    # Use the coercer like a normal schema object
+    result = coercer.validate(input_params)
+
+    # The result object contains the coerced value
+    result.valid? #=> true
+    result.value #=> { :whatever_id => 5, :amount => 123.45 }
+
+Custom Coercion
+---------------
+
+Coercion is designed to be totally extensible. You'll have to take my word
+for it, because there isn't much documentation at the moment.
+
+See `lib/rschema/coercion_wrapper/rack_params.rb` for an example of how to
+make a coercion wrapper.
+
+See all the classes in `lib/rschema/coercers/` for examples of how to make
+individual coercers.
+
+If you have any problems or questions about implementing custom coercion, feel
+free to contact me (Tom Dalling).
+
+
+Implementing Your Own Schema Types
+----------------------------------
 
 Schemas are objects that conform to a certain interface (i.e. a duck type).
 To create your own schema types, you just need to implement this interface.
 
+The interface consists of two methods: `call` and `with_wrapped_subschemas`.
+The `call` method is the interface for validating values.
+The `with_wrapped_subschemas` is necessary for coercion to work.
+If you have any problems or questions regarding this schema interface, feel
+free to contact me (Tom Dalling).
+
 Below is a custom schema for pairs – arrays with two elements of the same type.
-This is already possible using existing schemas (e.g. `Array(_String, _String)`),
+This is already possible using existing schemas (e.g. `array(_String, _String)`),
 and is only shown here for the purpose of demonstration.
 
     class PairSchema
@@ -423,19 +438,31 @@ and is only shown here for the purpose of demonstration.
         @subschema = subschema
       end
 
-      def call(pair, options=RSchema::Options.default)
+      #
+      # This method is mandatory.
+      #
+      # `pair` is the value to validate.
+      # `options` is an `RSchema::Options` object.
+      # This method must return a `RSchema::Result` object
+      #
+      def call(pair, options)
         return not_an_array_failure(pair) unless pair.is_a?(Array)
         return not_a_pair_failure(pair) unless pair.size == 2
 
+        # pass both array elements to `@subschema.call`
         subresults = pair.map { |x| @subschema.call(x, options) }
 
+        # check if both elements are valid according to @subschema
         if subresults.all?(&:valid?)
-          RSchema::Result.success(subresults.map(&:value).to_a)
+          RSchema::Result.success(subresults.map(&:value))
         else
           RSchema::Result.failure(subschema_error(subresults))
         end
       end
 
+      #
+      # This method is necessary for coercion to work
+      #
       def with_wrapped_subschemas(wrapper)
         PairSchema.new(wrapper.wrap(@subschema))
       end
@@ -458,25 +485,22 @@ and is only shown here for the purpose of demonstration.
               symbolic_name: :not_a_pair,
               schema: self,
               value: pair,
-              vars: {
-                expected_size: 2,
-                actual_size: pair.size,
-              }
             )
           )
         end
 
+        #
+        # Returns a hash of index => error
+        #
         def subschema_error(subresults)
           subresults
             .each_with_index
             .select { |(result, idx)| result.invalid? }
-            .map(&:reverse)
+            .map { |(result, idx)| [idx, result.error] }
             .to_h
         end
     end
 
-TODO: need to explain how to implement `#call` and `#with_wrapped_subschemas`
-
 Add your new schema class to the default DSL:
 
     module PairSchemaDSL
@@ -490,13 +514,13 @@ Add your new schema class to the default DSL:
 Then your schema is accessible from `RSchema.define`:
 
     gps_coordinate_schema = RSchema.define { pair(_Float) }
-    gps_coordinate_schema.call([1.2, 3.4]).valid? #=> true
+    gps_coordinate_schema.valid?([1.2, 3.4]) #=> true
 
 Coercion should work, as long as `#with_wrapped_subschemas` was implemented
 correctly.
 
-    coercer = RSchema::HTTPCoercer.wrap(gps_coordinate_schema)
-    result = coercer.call(['1', '2'])
+    coercer = RSchema::CoercionWrapper::RACK_PARAMS.wrap(gps_coordinate_schema)
+    result = coercer.validate(["1", "2"])
     result.valid? #=> true
     result.value #=> [1.0, 2.0]