rschema 3.0.1.pre5 → 3.0.2

data/lib/rschema/schemas/coercer.rb

@@ -1,5 +1,13 @@
 module RSchema
 module Schemas
+
+#
+# A schema that applies a coercer to a value, before passing the coerced
+# value to a subschema.
+#
+# This is not a type of schema that you would typically create yourself.
+# It is used internally to implement RSchema's coercion functionality.
+#
 class Coercer
   attr_reader :coercer, :subschema
 

data/lib/rschema/schemas/convenience.rb

@@ -2,21 +2,78 @@ require 'delegate'
 
 module RSchema
 module Schemas
+
+#
+# A wrapper that provides convenience methods for schema objects.
+#
+# Because this class inherits from `SimpleDelegator`, convenience wrappers
+# behave like their underlying schemas. That is, you can call methods on the
+# underlying schema object through the convenience wrapper.
+#
+# Schema objects only need to implement the `call` method to validate values.
+# This small interface is simple for schema classes to implement, but not
+# very descriptive when actually using the schema objects. So, to make
+# schema objects nicer to use, this class provides a variety of
+# more-descriptive methods like {#validate}, {#validate!}, {#valid?}, and
+# {#invalid?}.
+#
 class Convenience < SimpleDelegator
-  def initialize(raw_schema)
+  def initialize(underlying_schema)
     super
   end
 
-  def raw_schema
+  # @return [schema] the underlying schema object
+  def underlying_schema
     __getobj__
   end
 
+  #
+  # Applies the schema to a value
+  #
+  # This is that same as the `call` method available on all schema objects,
+  # except that the `options` param is optional.
+  #
+  # @param value [Object] The value to validate
+  # @param options [RSchema::Options]
+  #
+  # @return [RSchema::Result]
+  #
   def validate(value, options=Options.default)
     call(value, options)
   end
 
+  #
+  # Returns the validation error for the given value
+  #
+  # @param value [Object] The value to validate
+  # @param options [RSchema::Options]
+  #
+  # @return The error object if `value` is invalid, otherwise `nil`.
+  #
+  # @see Result#error
+  #
+  def error_for(value, options=Options.default)
+    result = underlying_schema.call(value, options)
+    if result.valid?
+      nil
+    else
+      result.error
+    end
+  end
+
+  #
+  # Applies the schema to a value, raising an exception if the value is invalid
+  #
+  # @param value [Object] The value to validate
+  # @param options [RSchema::Options]
+  #
+  # @raise [RSchema::Invalid] If the value is not valid
+  # @return [Object] The validated value
+  #
+  # @see Result#value
+  #
   def validate!(value, options=Options.default)
-    result = call(value, options)
+    result = underlying_schema.call(value, options)
     if result.valid?
       result.value
     else
@@ -24,11 +81,32 @@ class Convenience < SimpleDelegator
     end
   end
 
+  #
+  # Checks whether a value is valid or not
+  #
+  # @param value [Object] The value to validate
+  # @return [Boolean] `true` if the value is valid, otherwise `false`
+  #
   def valid?(value)
-    result = call(value, Options.new(fail_fast: true))
+    result = underlying_schema.call(value, Options.fail_fast)
     result.valid?
   end
 
+  #
+  # The opposite of {#valid?}
+  #
+  # @see #valid?
+  #
+  def invalid?(value)
+    not valid?(value)
+  end
+
+  #
+  # Wraps the given schema in a {Convenience}, if it isn't already wrapped.
+  #
+  # @param schema [schema] The schema to wrap
+  # @return {Convenience}
+  #
   def self.wrap(schema)
     if schema.is_a?(self)
       schema
@@ -37,15 +115,22 @@ class Convenience < SimpleDelegator
     end
   end
 
+  #
+  # Removes any {Convenience} wrappers from a schema
+  #
+  # @param schema [schema] The schema to unwrap
+  # @return [schema] The underlying schema, with all {Convenience} wrappers
+  #   removed
   def self.unwrap(schema)
     while schema.is_a?(self)
-      schema = schema.raw_schema
+      schema = schema.underlying_schema
     end
     schema
   end
 
+  # @!visibility private
   def with_wrapped_subschemas(wrapper)
-    self.class.new(wrapper.wrap(raw_schema))
+    self.class.new(wrapper.wrap(underlying_schema))
   end
 
 end

data/lib/rschema/schemas/enum.rb

@@ -1,5 +1,15 @@
 module RSchema
 module Schemas
+
+#
+# A schema that matches a values in a given set.
+#
+# @example Rock-Paper-Scissors values
+#     schema = RSchema.define { enum([:rock, :paper, :scissors]) }
+#     schema.valid?(:rock)  #=> true
+#     schema.valid?(:paper) #=> true
+#     schema.valid?(:gun)   #=> false
+#
 class Enum
   attr_reader :members, :subschema
 

data/lib/rschema/schemas/fixed_hash.rb

@@ -1,5 +1,19 @@
 module RSchema
 module Schemas
+
+#
+# A schema that matches `Hash` objects with known keys
+#
+# @example A typical fixed hash schema
+#     schema = RSchema.define do
+#       fixed_hash(
+#         name: _String,
+#         optional(:age) => _Integer,
+#       )
+#     end
+#     schema.valid?({ name: "Tom" }) #=> true
+#     schema.valid?({ name: "Dane", age: 55 }) #=> true
+#
 class FixedHash
   attr_reader :attributes
 
@@ -32,6 +46,28 @@ class FixedHash
     attributes.find{ |attr| attr.key == attr_key }
   end
 
+  #
+  # Creates a new {FixedHash} schema with the given attributes merged in
+  #
+  # @param new_attributes [Array<Attribute>] The attributes to merge
+  # @return [FixedHash] A new schema with the given attributes merged in
+  #
+  # @example Merging new attributes into an existing {Schemas::FixedHash} schema
+  #     person_schema = RSchema.define_hash {{
+  #       name: _String,
+  #       age: _Integer,
+  #     }}
+  #     person_schema.valid?(name: "t", age: 5) #=> true
+  #     person_schema.valid?(name: "t", age: 5, id: 3) #=> false
+  #
+  #     person_with_id_schema = RSchema.define do
+  #       person_schema.merge(attributes(
+  #         id: _Integer,
+  #       ))
+  #     end
+  #     person_with_id_schema.valid?(name: "t", age: 5, id: 3) #=> true
+  #     person_with_id_schema.valid?(name: "t", age: 5) #=> false
+  #
   def merge(new_attributes)
     merged_attrs = (attributes + new_attributes)
       .map { |attr| [attr.key, attr] }
@@ -41,6 +77,22 @@ class FixedHash
     self.class.new(merged_attrs)
   end
 
+  #
+  # Creates a new {FixedHash} schema with the given attributes removed
+  #
+  # @param attribute_keys [Array<Object>] The keys to remove
+  # @return [FixedHash] A new schema with the given attributes removed
+  #
+  # @example Removing an attribute
+  #     cat_and_dog = RSchema.define_hash {{
+  #       dog: _String,
+  #       cat: _String,
+  #     }}
+  #
+  #     only_cat = RSchema.define { cat_and_dog.without(:dog) }
+  #     only_cat.valid?({ cat: 'meow' }) #=> true
+  #     only_cat.valid?({ cat: 'meow', dog: 'woof' }) #=> false
+  #
   def without(attribute_keys)
     filtered_attrs = attributes
       .reject { |attr| attribute_keys.include?(attr.key) }
@@ -104,16 +156,11 @@ class FixedHash
     subresults_by_key
   end
 
-  def failure_error(results)
-    error = {}
-
-    results.each do |key, attr_result|
-      if attr_result.invalid?
-        error[key] = attr_result.error
-      end
-    end
-
-    error
+  def failure_error(subresults)
+    subresults
+      .select{ |_, result| result.invalid? }
+      .map{ |key, result| [key, result.error] }
+      .to_h
   end
 
   def success_value(subresults)

data/lib/rschema/schemas/fixed_length_array.rb

@@ -1,5 +1,17 @@
 module RSchema
 module Schemas
+
+#
+# A schema that represents an array of fixed length
+#
+# Each element in the fixed-length array has its own subschema
+#
+# @example A fixed-length array schema
+#     schema = RSchema.define { array(_Integer, _String) }
+#     schema.valid?([5, "hello"]) #=> true
+#     schema.valid?([5]) #=> false
+#     schema.valid?([5, "hello", "world"]) #=> false
+#
 class FixedLengthArray
   attr_reader :subschemas
 

data/lib/rschema/schemas/maybe.rb

@@ -1,5 +1,16 @@
 module RSchema
 module Schemas
+
+#
+# A schema representing that a value may be `nil`
+#
+# If the value is not `nil`, it must conform to the subschema
+#
+# @example A nil-able Integer
+#     schema = RSchema.define{ maybe(_Integer) }
+#     schema.valid?(5) #=> true
+#     schema.valid?(nil) #=> true
+#
 class Maybe
   attr_reader :subschema
 
@@ -8,7 +19,7 @@ class Maybe
   end
 
   def call(value, options)
-    if value == nil
+    if nil == value
       Result.success(value)
     else
       @subschema.call(value, options)

data/lib/rschema/schemas/pipeline.rb

@@ -1,5 +1,20 @@
 module RSchema
 module Schemas
+
+#
+# A schema that chains together an ordered list of other schemas
+#
+# @example A schema for positive floats
+#     schema = RSchema.define do
+#       pipeline(
+#         _Float,
+#         predicate{ |f| f > 0.0 },
+#       )
+#     end
+#     schema.valid?(6.2) #=> true
+#     schema.valid?('hi') #=> false (because it's not a Float)
+#     schema.valid?(-6.2) #=> false (because predicate failed)
+#
 class Pipeline
   attr_reader :subschemas
 

data/lib/rschema/schemas/predicate.rb

@@ -1,5 +1,16 @@
 module RSchema
 module Schemas
+
+#
+# A schema that uses a given block to determine whether a value is valid
+#
+# @example A predicate that checks if numbers are odd
+#     schema = RSchema.define do
+#       predicate('odd'){ |x| x.odd? }
+#     end
+#     schema.valid?(5) #=> true
+#     schema.valid?(6) #=> false
+#
 class Predicate
   attr_reader :block, :name
 

data/lib/rschema/schemas/set.rb

@@ -2,6 +2,16 @@ require 'set'
 
 module RSchema
 module Schemas
+
+#
+# A schema that matches `Set` objects (from the Ruby standard library)
+#
+# @example A set of integers
+#     require 'set'
+#     schema = RSchema.define { set(_Integer) }
+#     schema.valid?(Set[1, 2, 3]) #=> true
+#     schema.valid?(Set[:a, :b, :c]) #=> false
+#
 class Set
   attr_reader :subschema
 

data/lib/rschema/schemas/sum.rb

@@ -1,5 +1,16 @@
 module RSchema
 module Schemas
+
+#
+# A schema that represents a "sum type"
+#
+# Values must conform to one of the subschemas.
+#
+# @example A schema that matches both Integers and Strings
+#     schema = RSchema.define { either(_String, _Integer) }
+#     schema.valid?("hello") #=> true
+#     schema.valid?(5) #=> true
+#
 class Sum
   attr_reader :subschemas
 

data/lib/rschema/schemas/type.rb

@@ -1,5 +1,22 @@
 module RSchema
 module Schemas
+
+#
+# A schema that matches values of a given type (i.e. `value.is_a?(type)`)
+#
+# @example An Integer schema
+#     schema = RSchema.define { _Integer }
+#     schema.valid?(5) #=> true
+#
+# @example A namespaced type
+#     schema = RSchema.define do
+#       # This will not work:
+#       # _ActiveWhatever::Thing
+#
+#       # This will work:
+#       type(ActiveWhatever::Thing)
+#     end
+#
 class Type
   attr_reader :type
 

data/lib/rschema/schemas/variable_hash.rb

@@ -1,5 +1,15 @@
 module RSchema
 module Schemas
+
+#
+# A schema that matches variable-sized `Hash` objects, where the keys are _not_
+# known ahead of time.
+#
+# @example A hash of integers to strings
+#     schema = RSchema.define { variable_hash(_Integer => _String) }
+#     schema.valid?({ 5 => "hello", 7 => "world" }) #=> true
+#     schema.valid?({}) #=> true
+#
 class VariableHash
   attr_reader :key_schema, :value_schema
 

data/lib/rschema/schemas/variable_length_array.rb

@@ -1,5 +1,15 @@
 module RSchema
 module Schemas
+
+#
+# A schema that matches variable-length arrays, where all elements conform to
+# a single subschema
+#
+# @example A variable-length array schema
+#     schema = RSchema.define { array(_Integer) }
+#     schema.valid?([1,2,3]) #=> true
+#     schema.valid?([]) #=> true
+#
 class VariableLengthArray
   attr_accessor :element_schema
 

data/lib/rschema/version.rb

@@ -1,3 +1,3 @@
 module RSchema
-  VERSION = '3.0.1.pre5'
+  VERSION = '3.0.2'
 end