rschema 3.0.1.pre3 → 3.0.1.pre4

data/lib/rschema.rb

@@ -1,36 +1,123 @@
+require 'docile'
+
 require 'rschema/options'
 require 'rschema/error'
 require 'rschema/result'
-require 'rschema/schemas/type'
-require 'rschema/schemas/maybe'
-require 'rschema/schemas/enum'
-require 'rschema/schemas/boolean'
-require 'rschema/schemas/sum'
-require 'rschema/schemas/pipeline'
-require 'rschema/schemas/anything'
-require 'rschema/schemas/predicate'
-require 'rschema/schemas/set'
-require 'rschema/schemas/variable_hash'
-require 'rschema/schemas/fixed_hash'
-require 'rschema/schemas/variable_length_array'
-require 'rschema/schemas/fixed_length_array'
+require 'rschema/schemas'
 require 'rschema/dsl'
-require 'rschema/http_coercer'
+require 'rschema/coercers'
+require 'rschema/coercion_wrapper'
 
+#
+# Schema-based validation and coercion
+#
 module RSchema
-  def self.define(&block)
-    default_dsl.instance_eval(&block)
+
+  #
+  # Runs a block using a DSL.
+  #
+  # @param dsl [Object] An optional DSL object to run the block with.
+  #   Uses {RSchema#default_dsl} if nil.
+  # @yield Invokes the given block with access to the methods on `dsl`.
+  # @return The return value of the given block (usually some kind of schema object)
+  #
+  # @example Creating a typical fixed hash schema
+  #   person_schema = RSchema.define do
+  #     fixed_hash(
+  #       name: _String,
+  #       age: _Integer,
+  #     )
+  #   end
+  #
+  def self.define(dsl = nil, &block)
+    schema = dsl_eval(dsl, &block)
+    Schemas::Convenience.wrap(schema)
   end
 
+  def self.dsl_eval(dsl = nil, &block)
+    Docile::Execution.exec_in_proxy_context(
+      dsl || default_dsl,
+      Docile::FallbackContextProxy,
+      &block
+    )
+  end
+
+  #
+  # A shortcut for:
+  #
+  #     RSchema.define do
+  #       fixed_hash(...)
+  #     end
+  #
+  # @yield Invokes the given block with access to the methods of the default DSL.
+  # @yieldreturn The attributes of the hash schema (the argument to {DSL#fixed_hash}).
+  # @return [Schemas::FixedHash]
+  #
+  # @example A typical schema
+  #
+  #     person_schema = RSchema.define_hash {{
+  #       name: _String,
+  #       age: _Integer,
+  #     }}
+  #
   def self.define_hash(&block)
-    default_dsl.Hash(define(&block))
+    Schemas::Convenience.wrap(
+      default_dsl.fixed_hash(dsl_eval(&block))
+    )
   end
 
+  #
+  # A shortcut for:
+  #
+  #     RSchema.define do
+  #       predicate { ... }
+  #     end
+  #
+  # @param name [String] An arbitraty name for the predicate schema.
+  # @yield [value] Yields a single value.
+  # @yieldreturn [Boolean] Truthy if the value is valid, otherwise falsey.
+  # @return [Schemas::Predicate]
+  #
+  # @example A predicate schema that only allows `odd?` objects.
+  #
+  #     odd_schema = RSchema.define_predicate('odd') do |x|
+  #       x.odd?
+  #     end
+  #
+  # @see DSL#predicate
+  #
+  def self.define_predicate(name = nil, &block)
+    Schemas::Convenience.wrap(
+      default_dsl.predicate(name, &block)
+    )
+  end
+
+  #
+  # @return The default DSL object.
+  # @see DefaultDSL
+  #
   def self.default_dsl
     @default_dsl ||= DefaultDSL.new
   end
 
+  #
+  # The class of the default RSchema DSL.
+  #
+  # By default, this only includes the methods from the {RSchema::DSL} mixin.
+  #
+  # Your own code and other gems may include modules into this class, in order
+  # to add new methods to the default DSL.
+  #
   class DefaultDSL
     include RSchema::DSL
   end
+
+  class Invalid < StandardError
+    attr_reader :validation_error
+
+    def initialize(validation_error)
+      super()
+      @validation_error = validation_error
+    end
+  end
 end

data/lib/rschema/coercers.rb

@@ -0,0 +1,3 @@
+Dir.glob(File.join(__dir__, 'coercers/**/*.rb')).each do |path|
+  require path
+end

data/lib/rschema/coercers/any.rb

@@ -0,0 +1,40 @@
+module RSchema
+module Coercers
+
+  class Any
+    attr_reader :subcoercers
+
+    def self.[](*subbuilders)
+      Builder.new(subbuilders)
+    end
+
+    def initialize(subcoercers)
+      @subcoercers = subcoercers
+    end
+
+    def call(value)
+      subcoercers.each do |coercer|
+        result = coercer.call(value)
+        return result if result.valid?
+      end
+      Result.failure
+    end
+
+    class Builder
+      attr_reader :subbuilders
+
+      def initialize(subbuilders)
+        @subbuilders = subbuilders
+      end
+
+      def build(schema)
+        subcoercers = subbuilders.map do |builder|
+          builder.build(schema)
+        end
+        Any.new(subcoercers)
+      end
+    end
+  end
+
+end
+end

data/lib/rschema/coercers/boolean.rb

@@ -0,0 +1,30 @@
+module RSchema
+module Coercers
+
+  module Boolean
+    extend self
+
+    TRUTHY_STRINGS = ['on', '1', 'true', 'yes']
+    FALSEY_STRINGS = ['off', '0', 'false', 'no']
+
+    def build(schema)
+      self
+    end
+
+    def call(value)
+      case value
+      when true, false then Result.success(value)
+      when nil then Result.success(false)
+      when String
+        case
+        when TRUTHY_STRINGS.include?(value.downcase) then Result.success(true)
+        when FALSEY_STRINGS.include?(value.downcase) then Result.success(false)
+        else Result.failure
+        end
+      else Result.failure
+      end
+    end
+  end
+
+end
+end

data/lib/rschema/coercers/chain.rb

@@ -0,0 +1,41 @@
+module RSchema
+module Coercers
+
+  class Chain
+    attr_reader :subcoercers
+
+    def self.[](*subbuilders)
+      Builder.new(subbuilders)
+    end
+
+    def initialize(subcoercers)
+      @subcoercers = subcoercers
+    end
+
+    def call(value)
+      result = Result.success(value)
+      subcoercers.each do |coercer|
+        result = coercer.call(result.value)
+        break if result.invalid?
+      end
+      result
+    end
+
+    class Builder
+      attr_reader :subbuilders
+
+      def initialize(subbuilders)
+        @subbuilders = subbuilders
+      end
+
+      def build(schema)
+        subcoercers = subbuilders.map do |builder|
+          builder.build(schema)
+        end
+        Chain.new(subcoercers)
+      end
+    end
+  end
+
+end
+end

data/lib/rschema/coercers/date.rb

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

data/lib/rschema/coercers/fixed_hash/default_booleans_to_false.rb

@@ -0,0 +1,62 @@
+require 'set'
+
+module RSchema
+module Coercers
+module FixedHash
+
+  # The HTTP standard says that when a form is submitted, all unchecked
+  # check boxes will _not_ be sent to the server. That is, they will not
+  # be present at all in the params hash.
+  #
+  # This class coerces these missing values into `false`.
+  class DefaultBooleansToFalse
+    attr_reader :hash_attributes
+
+    def self.build(schema)
+      new(schema)
+    end
+
+    def initialize(fixed_hash_schema)
+      #TODO: make fixed hash attributes frozen, and eliminate dup
+      @hash_attributes = fixed_hash_schema.attributes.map(&:dup)
+    end
+
+    def call(value)
+      Result.success(default_bools_to_false(value))
+    end
+
+    private
+      def default_bools_to_false(hash)
+        missing_keys = keys_for_bool_defaulting - hash.keys
+
+        if missing_keys.any?
+          defaults = missing_keys.map{ |k| [k, false] }.to_h
+          hash.merge(defaults)
+        else
+          hash # no coercion necessary
+        end
+      end
+
+      def keys_for_bool_defaulting
+        @keys_for_bool_defaulting ||= Set.new(
+          hash_attributes
+            .reject(&:optional)
+            .select { |attr| is_bool_schema?(attr.value_schema) }
+            .map(&:key)
+        )
+      end
+
+      def is_bool_schema?(schema)
+        # dig through all the coercers
+        non_coercer = schema
+        while non_coercer.is_a?(Schemas::Coercer)
+          non_coercer = non_coercer.subschema
+        end
+
+        non_coercer.is_a?(Schemas::Boolean)
+      end
+  end
+
+end
+end
+end

data/lib/rschema/coercers/fixed_hash/remove_extraneous_attributes.rb

@@ -0,0 +1,42 @@
+module RSchema
+module Coercers
+module FixedHash
+
+  class RemoveExtraneousAttributes
+    attr_reader :hash_attributes
+
+    def self.build(schema)
+      new(schema)
+    end
+
+    def initialize(fixed_hash_schema)
+      #TODO: make fixed hash attributes frozen, and eliminate dup
+      @hash_attributes = fixed_hash_schema.attributes.map(&:dup)
+    end
+
+    def call(value)
+      Result.success(remove_extraneous_elements(value))
+    end
+
+    private
+
+      def remove_extraneous_elements(hash)
+        keys_to_remove = hash.keys - valid_keys
+
+        if keys_to_remove.any?
+          hash.dup.tap do |stripped_hash|
+            keys_to_remove.each { |k| stripped_hash.delete(k) }
+          end
+        else
+          hash
+        end
+      end
+
+      def valid_keys
+        @valid_keys ||= hash_attributes.map(&:key)
+      end
+  end
+
+end
+end
+end

data/lib/rschema/coercers/fixed_hash/symbolize_keys.rb

@@ -0,0 +1,62 @@
+require 'set'
+
+module RSchema
+module Coercers
+module FixedHash
+
+  class SymbolizeKeys
+    attr_reader :hash_attributes
+
+    def self.build(schema)
+      new(schema)
+    end
+
+    def initialize(fixed_hash_schema)
+      #TODO: make fixed hash attributes frozen, and eliminate dup
+      @hash_attributes = fixed_hash_schema.attributes.map(&:dup)
+    end
+
+    def call(value)
+      Result.success(symbolize_keys(value))
+    end
+
+    private
+
+      def symbolize_keys(hash)
+        keys = keys_to_symbolize(hash)
+        if keys.any?
+          hash.dup.tap do |new_hash|
+            keys.each { |k| new_hash[k.to_sym] = new_hash.delete(k) }
+          end
+        else
+          hash
+        end
+      end
+
+      def keys_to_symbolize(hash)
+        non_string_keys = Set.new(hash.keys) - string_keys
+        non_string_keys.intersection(symbol_keys_as_strings)
+      end
+
+      def symbol_keys_as_strings
+        @symbol_keys_as_strings ||= Set.new(
+          all_keys
+            .select{ |k| k.is_a?(::Symbol) }
+            .map(&:to_s)
+        )
+      end
+
+      def string_keys
+        @string_keys ||= Set.new(
+          all_keys.select { |k| k.is_a?(::String) }
+        )
+      end
+
+      def all_keys
+        @all_keys ||= hash_attributes.map(&:key)
+      end
+  end
+
+end
+end
+end