rschema 3.0.1.pre3 → 3.0.1.pre4

data/lib/rschema/coercers/float.rb

@@ -0,0 +1,18 @@
+module RSchema
+module Coercers
+
+  module Float
+    extend self
+
+    def build(schema)
+      self
+    end
+
+    def call(value)
+      flt = Float(value) rescue nil
+      flt ? Result.success(flt) : Result.failure
+    end
+  end
+
+end
+end

data/lib/rschema/coercers/integer.rb

@@ -0,0 +1,18 @@
+module RSchema
+module Coercers
+
+  module Integer
+    extend self
+
+    def build(schema)
+      self
+    end
+
+    def call(value)
+      int = Integer(value) rescue nil
+      int ? Result.success(int) : Result.failure
+    end
+  end
+
+end
+end

data/lib/rschema/coercers/symbol.rb

@@ -0,0 +1,21 @@
+module RSchema
+module Coercers
+
+  module Symbol
+    extend self
+
+    def build(schema)
+      self
+    end
+
+    def call(value)
+      case value
+      when ::Symbol then Result.success(value)
+      when ::String then Result.success(value.to_sym)
+      else Result.failure
+      end
+    end
+  end
+
+end
+end

data/lib/rschema/coercers/time.rb

@@ -0,0 +1,25 @@
+module RSchema
+module Coercers
+
+  module Time
+    extend self
+
+    def build(schema)
+      self
+    end
+
+    def call(value)
+      case value
+      when ::Time
+        Result.success(value)
+      when ::String
+        time = ::Time.parse(value) rescue nil
+        time ? Result.success(time) : Result.failure
+      else
+        Result.failure
+      end
+    end
+  end
+
+end
+end

data/lib/rschema/coercion_wrapper.rb

@@ -0,0 +1,46 @@
+module RSchema
+  class CoercionWrapper
+    def initialize(&initializer)
+      @builder_by_schema = {}
+      @builder_by_type = {}
+      instance_eval(&initializer) if initializer
+    end
+
+    def coerce(schema_type, with:)
+      @builder_by_schema[schema_type] = with
+    end
+
+    def coerce_type(type, with:)
+      @builder_by_type[type] = with
+    end
+
+    def wrap(schema)
+      wrapped_schema = schema.with_wrapped_subschemas(self)
+      wrap_with_coercer(wrapped_schema)
+    end
+
+    private
+
+      def builder_for_schema(schema)
+        @builder_by_schema.fetch(schema.class) do
+          if schema.is_a?(Schemas::Type)
+            @builder_by_type.fetch(schema.type, nil)
+          else
+            nil
+          end
+        end
+      end
+
+      def wrap_with_coercer(schema)
+        builder = builder_for_schema(schema)
+        if builder
+          coercer = builder.build(schema)
+          Schemas::Coercer.new(coercer, schema)
+        else
+          schema
+        end
+      end
+
+  end
+end
+

data/lib/rschema/coercion_wrapper/rack_params.rb

@@ -0,0 +1,21 @@
+module RSchema
+class CoercionWrapper
+
+  RACK_PARAMS = CoercionWrapper.new do
+    coerce_type Symbol, with: Coercers::Symbol
+    coerce_type Integer, with: Coercers::Integer
+    coerce_type Float, with: Coercers::Float
+    coerce_type Time, with: Coercers::Time
+    coerce_type Date, with: Coercers::Date
+
+    coerce Schemas::Boolean, with: Coercers::Boolean
+    coerce Schemas::FixedHash, with: Coercers::Chain[
+      Coercers::FixedHash::SymbolizeKeys,
+      Coercers::FixedHash::RemoveExtraneousAttributes,
+      Coercers::FixedHash::DefaultBooleansToFalse,
+    ]
+  end
+
+end
+end
+

data/lib/rschema/dsl.rb

@@ -1,83 +1,318 @@
 module RSchema
+  #
+  # A mixin containing all the standard RSchema DSL methods.
+  #
+  # If you are making a custom DSL, you can include this mixin to get ONLY the
+  # standard RSchema DSL methods, without any of the extra ones that may have
+  # been included by third-party gems.
+  #
+  # @note Do not include your custom DSL methods into this module.
+  #   Include them into the {DefaultDSL} class instead.
+  #
+  # @see RSchema.define
+  # @see RSchema.default_dsl
+  #
   module DSL
+    OptionalWrapper = Struct.new(:key)
+
+    #
+    # Creates a {Schemas::Type} schema.
+    #
+    # The preferred way to create type schemas is using an underscore, like:
+    #
+    #     _Integer
+    #
+    # The DSL will turn the above code into:
+    #
+    #     type(Integer)
+    #
+    # Underscores will not work for namespaced types (types that include `::`).
+    # In that case, it is necessary to use the `type` method:
+    #
+    #     _MyNamespace::MyType # this will NOT work
+    #     type(MyNamespace::MyType) # this will work
+    #
+    # @param type [Class]
+    # @return [Schemas::Type]
+    #
+    # @example An `Integer` type schema
+    #     type(Integer)
+    #     # exactly the same as:
+    #     _Integer
+    #
     def type(type)
       Schemas::Type.new(type)
     end
-    alias_method :_, :type
 
-    def Array(*subchemas)
-      if subchemas.count == 1
-        Schemas::VariableLengthArray.new(subchemas.first)
+    #
+    # Creates a {Schemas::VariableLengthArray} if given one argument, otherwise
+    # creates a {Schemas::FixedLengthArray}
+    #
+    # @param subschemas [Array<schema>] one or more schema objects representing elements
+    #   in the array.
+    # @return [Schemas::VariableLengthArray, Schemas::FixedLengthArray]
+    #
+    # @example A variable-length array schema
+    #     array(_Integer)
+    #     # matches [1, 2, 3, 4]
+    #
+    # @example A fixed-length array schema
+    #     array(_Integer, _String)
+    #     # matches [5, "hello"]
+    #
+    def array(*subschemas)
+      subschemas = subschemas.map{ |ss| inconvenience(ss) }
+
+      if subschemas.count == 1
+        Schemas::VariableLengthArray.new(subschemas.first)
       else
-        Schemas::FixedLengthArray.new(subchemas)
+        Schemas::FixedLengthArray.new(subschemas)
       end
     end
 
-    def Boolean
+    #
+    # Returns the {Schemas::Boolean} schema
+    #
+    # @return [Schemas::Boolean]
+    #
+    # @example The boolean schema
+    #     boolean
+    #     # matches only `true` and `false`
+    #
+    def boolean
       Schemas::Boolean.instance
     end
 
-    def Hash(attribute_hash)
-      Schemas::FixedHash.new(__fixed_hash_attributes(attribute_hash))
-    end
-
-    def Hash_based_on(preexisting_hash_schema, new_attributes_hash)
-      old_attrs = preexisting_hash_schema.attributes
-        .map{ |attr| [attr.key, attr] }
-        .to_h
-
-      new_attrs = __fixed_hash_attributes(new_attributes_hash)
-        .map{ |attr| [attr.key, attr] }
-        .to_h
-
-      merged_attrs = old_attrs.merge(new_attrs)
-        .values
-        .reject{ |attr| attr.value_schema.nil? }
-
-      Schemas::FixedHash.new(merged_attrs)
+    #
+    # Creates a {Schemas::FixedHash} schema
+    #
+    # @param attribute_hash (see #attributes)
+    # @return [Schemas::FixedHash]
+    #
+    # @example A typical fixed hash schema
+    #     fixed_hash(
+    #       name: _String,
+    #       optional(:age) => _Integer,
+    #     )
+    #     # matches { name: "Tom" }
+    #     # matches { name: "Dane", age: 55 }
+    #
+    def fixed_hash(attribute_hash)
+      Schemas::FixedHash.new(attributes(attribute_hash))
     end
+    alias_method :hash, :fixed_hash
 
-    def Set(subschema)
-      Schemas::Set.new(subschema)
+    #
+    # Creates a {Schemas::Set} schema
+    #
+    # @param subschema [schema] A schema representing the elements of the set
+    # @return [Schemas::Set]
+    #
+    # @example A set of integers
+    #     set(_Integer)
+    #     # matches Set[1,2,3]
+    #
+    def set(subschema)
+      Schemas::Set.new(inconvenience(subschema))
     end
 
+    #
+    # Wraps a key in an {OptionalWrapper}, for use with the {#fixed_hash} or
+    # {#attributes} methods.
+    #
+    # @param key [Object] Any arbitrary value
+    # @return [OptionalWrapper] An {OptionalWrapper} containing the given key.
+    #
+    # @see OptionalWrapper
+    # @see #fixed_hash
+    # @see #attributes
+    #
+    # @example (see #fixed_hash)
+    #
     def optional(key)
       OptionalWrapper.new(key)
     end
 
-    def VariableHash(subschemas)
+    #
+    # Creates a {Schemas::VariableHash} schema
+    #
+    # @param subschemas [Hash] A hash with a single key, and a single value.
+    #   The key is a schema representing all keys.
+    #   The value is a schema representing all values.
+    # @return [Schemas::VariableHash]
+    #
+    # @example A hash of integers to strings
+    #     variable_hash(_Integer => _String)
+    #     # matches { 5 => "hello", 7 => "world" }
+    #
+    def variable_hash(subschemas)
       unless subschemas.is_a?(Hash) && subschemas.size == 1
         raise ArgumentError, 'argument must be a Hash of size 1'
       end
 
       key_schema, value_schema = subschemas.first
-      Schemas::VariableHash.new(key_schema, value_schema)
+      Schemas::VariableHash.new(
+        inconvenience(key_schema),
+        inconvenience(value_schema),
+      )
+    end
+
+    #
+    # Turns an "attribute hash" into an array of {Schemas::FixedHash::Attribute}.
+    # Primarily for use with {Schemas::FixedHash#merge}.
+    #
+    # @param attribute_hash [Hash<key, schema>] A hash of keys to subschemas.
+    #   The values of this parameter must be schema objects.
+    #   The keys should be the exact keys expected in the represented `Hash`
+    #   (`Strings`, `Symbols`, whatever). Keys can be wrapped with {#optional}
+    #   to indicate that the key can be missing in the represented `Hash`.
+    # @return [Array<Schemas::FixedHash::Attribute>]
+    #
+    # @see Schemas::FixedHash#merge
+    #
+    # @example Merging new attributes into an existing {Schemas::FixedHash} schema
+    #     person_schema = fixed_hash(
+    #       first_name: _String,
+    #       last_name: _String,
+    #     )
+    #
+    #     person_record_schema = person_schema.merge(attributes(
+    #       id: _Integer,
+    #       optional(:updated_at) => _Time,
+    #     ))
+    #
+    #     # person_record_schema matches:
+    #     #  {
+    #     #    id: 3,
+    #     #    updated_at: Time.now,
+    #     #    first_name: "Tom",
+    #     #    last_name: "Dalling",
+    #     #  }
+    #
+    def attributes(attribute_hash)
+      attribute_hash.map do |dsl_key, value_schema|
+        optional = dsl_key.is_a?(OptionalWrapper)
+        key = optional ? dsl_key.key : dsl_key
+        Schemas::FixedHash::Attribute.new(key, inconvenience(value_schema), optional)
+      end
     end
 
+    #
+    # Creates a {Schemas::Maybe} schema
+    #
+    # @param subschema [schema] A schema representing the value, if the value
+    #   is not `nil`.
+    # @return [Schemas::Maybe]
+    #
+    # @example A nullable Integer
+    #     maybe(_Integer)
+    #     # matches 5
+    #     # matches nil
+    #
     def maybe(subschema)
-      Schemas::Maybe.new(subschema)
+      Schemas::Maybe.new(inconvenience(subschema))
     end
 
+    #
+    # Creates a {Schemas::Enum} schema
+    #
+    # @param valid_values [Array<Object>] An array of all possible valid values.
+    # @param subschema [schema] A schema that represents all enum members.
+    #   If this is `nil`, the schema is inferred to be the type of the first
+    #   element in `valid_values` (e.g. `enum([:a,:b,:c])` will have `_Symbol`
+    #   as the inferred subschema).
+    # @return [Schemas::Enum]
+    #
+    # @example Valid Rock-Paper-Scissors turn values
+    #     enum([:rock, :paper, :scissors])
+    #     # matches :rock
+    #     # matches :paper
+    #     # matches :scissors
+    #
     def enum(valid_values, subschema=nil)
+      subschema = inconvenience(subschema) if subschema
       Schemas::Enum.new(valid_values, subschema || type(valid_values.first.class))
     end
 
+    #
+    # Creates a {Schemas::Sum} schema.
+    #
+    # @param subschemas [Array<schema>] Schemas representing all the possible
+    #   valid values.
+    # @return [Schemas::Sum]
+    #
+    # @example A schema that matches both Integers and Strings
+    #     either(_String, _Integer)
+    #     # matches "hello"
+    #     # matches 1337
+    #
     def either(*subschemas)
+      subschemas = subschemas.map{ |ss| inconvenience(ss) }
       Schemas::Sum.new(subschemas)
     end
 
-    def predicate(&block)
-      Schemas::Predicate.new(block)
+    #
+    # Creates a {Schemas::Predicate} schema.
+    #
+    # @param name [String] An optional name for the predicate schema. This
+    #   serves no purpose other than to provide useful debugging information,
+    #   or perhaps some metadata for the schema.
+    # @yield Values being validated are yielded to the given block. The return
+    #   value of the block indicates whether the value is valid or not.
+    # @yieldparam value [Object] The value being validated
+    # @yieldreturn [Boolean] Truthy if the value is valid, otherwise falsey.
+    # @return [Schemas::Predicate]
+    #
+    # @example A predicate that checks if numbers are odd
+    #     predicate('odd'){ |x| x.odd? }
+    #     # matches 5
+    #
+    def predicate(name = nil, &block)
+      Schemas::Predicate.new(name, &block)
     end
 
+    #
+    # Creates a {Schemas::Pipeline} schema.
+    #
+    # @param subschemas [Array<schema>] The schemas to be pipelined together,
+    #   in order.
+    # @return [Schemas::Pipeline]
+    #
+    # @example A schema for positive floats
+    #     pipeline(
+    #       _Float,
+    #       predicate{ |f| f > 0.0 },
+    #     )
+    #     # matches 6.2
+    #
     def pipeline(*subschemas)
+      subschemas = subschemas.map{ |ss| inconvenience(ss) }
       Schemas::Pipeline.new(subschemas)
     end
 
+    #
+    # Returns the {Schemas::Anything} schema.
+    #
+    # @return [Schemas::Anything]
+    #
+    # @example The anything schema
+    #   anything
+    #   # matches nil
+    #   # matches 6.2
+    #   # matches { hello: Time.now }
+    #
     def anything
       Schemas::Anything.instance
     end
 
+    def convenience(schema)
+      Schemas::Convenience.wrap(schema)
+    end
+
+    def inconvenience(schema)
+      Schemas::Convenience.unwrap(schema)
+    end
+
     def method_missing(sym, *args, &block)
       type = sym.to_s
       if type.start_with?('_') && args.empty? && block.nil?
@@ -88,16 +323,10 @@ module RSchema
       end
     end
 
-    OptionalWrapper = Struct.new(:key)
-
-    private
-
-      def __fixed_hash_attributes(attribute_hash)
-        attribute_hash.map do |dsl_key, value_schema|
-          optional = dsl_key.kind_of?(OptionalWrapper)
-          key = optional ? dsl_key.key : dsl_key
-          Schemas::FixedHash::Attribute.new(key, value_schema, optional)
-        end
-      end
+    # @!visibility private
+    def respond_to?(sym, include_all=false)
+      # check if method starts with an underscore followed by a capital
+      super || !!sym.to_s.match(/\A_[A-Z]/)
+    end
   end
 end