rack-params 0.0.1.pre5 → 0.0.1.pre6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1007badc8d33a5465e1d7facda42c81901f4b5ad
-  data.tar.gz: a0d6fb178dc571d748ee5bb452db6a79502c8b15
+  metadata.gz: 1b8f9f809d52259627ff17cd8f7ac0950d239bd0
+  data.tar.gz: fe7397ffc2e416cac5984e88acdd9d9266d00220
 SHA512:
-  metadata.gz: 6f9d9e7469c1855f94b40b151c27a1d07ea1872d1c1c0dbd81addd5ead29dfae38a91df31af3378498b15a78e2a94f2cbb3809c38059bbf0a0fb3ffe8a677cf2
-  data.tar.gz: ac8475ffbc12725fb09b60890a225baa00037d9a37ee8c77e6fb8b5e0fb110a8443d11c27c68e87b9bc324c00b759c9bc5bd4a7621965ba82c67ed6fe624f77a
+  metadata.gz: 7927e8dd9ea5d6e0d0c047fd62a2d9e582e32f7a072c607aee42db9a0ea5dfda2db7309dbd30f72b5831665769fb9813584cb8feb0542275f2d7dd683e9662eb
+  data.tar.gz: 941558bf50cfd8cb34c5cdf0d08493a1df7673f9246251ccf028998c0f0973c5cef769b40c3207f83190f67b73e326d5788c6e138d96cba6875c899eca9d97d7

data/.gitignore

@@ -3,6 +3,7 @@
 /_yardoc/
 /coverage/
 /docs/
+/doc/
 /pkg/
 /spec/reports/
 /tmp/
@@ -12,3 +13,4 @@
 spec/examples.txt
 /.byebug_history
 /Gemfile.lock
+/CHANGELOG.html

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+All notable changes to `Rack::Params` will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+This is a pretty major refactor, but since we're not really released
+at all yet, I'm just including highlights in the changelog - check the
+diff for explicit changes, but so much got moved around, I'm not sure
+that'll be easy. Such are the perogotives of personal projects :)
+
+* added a changelog!
+* `#param` and `#every` now take a block for any type, which is passed
+  the value for transformation (think #map), which makes the
+  Hash/Array handling less special (though still special, since
+  they're recursed, not transformed given the block).
+* extracted the `Validator` module from `Context`; easier to test,
+  makes more sense architecturally (context is only concerned with
+  being `self` for the block), and allows the use of the validation
+  helpers elsewhere.
+* much more robust specs.
+
+### [0.0.1.pre5]
+- all basic functionality

data/README.md

@@ -3,6 +3,17 @@
 
 `Rack::Request.params` validation and type coercion, on Rack.
 
+## Usage
+
+**[Documentation](https://lygaret.github.io/rack-params/)**
+
+1. Include `Rack::Params` to get the `.validator`, `#validate` and `#validate!` methods.
+2. Call `.validator(name, options = {}, &code)` to register a named validator for use later.
+3. Call `#validate(name = nil, params = request.params, options = {}, &code)` to build a new result, with the results of validation and coercion.
+4. The blocks passed to the validation methods run in the context of `HashContext` and `ArrayContext`, which is where the coercion methods are defined.
+
+## Example
+
 ```ruby
 # NOTE (to self) - if this changes, update `readme_spec.rb`
 
@@ -16,8 +27,8 @@ class SomeExampleApp
     param :title,   String,   required: true
     param :created, DateTime
     
-    param :tags, Array, sep: " " do
-      every Symbol
+    param :tags, Array do
+      every :symbol
     end
     
     param :content, Hash, required: true do
@@ -106,15 +117,6 @@ Or install it yourself as:
 
     $ gem install rack-params
 
-## Usage
-
-**[RDoc @ master - Rack::Params](http://www.rubydoc.info/github/lygaret/rack-params/master)**
-
-1. Include `Rack::Params` to get the `.validator`, `#validate` and `#validate!` methods.
-2. Call `.validator(name, options = {}, &code)` to register a named validator for use later.
-3. Call `#validate(name = nil, params = request.params, options = {}, &code)` to build a new result, with the results of validation and coercion.
-4. The blocks passed to the validation methods run in the context of `HashContext` and `ArrayContext`, which is where the coercion methods are defined.
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/Rakefile

@@ -8,7 +8,7 @@ require "coveralls/rake/task"
 
 import(*Dir.glob("./lib/rack/params/**/*.rake"))
 
-CLOBBER << "docs"
+CLOBBER << "doc"
 CLOBBER << "coverage"
 
 RSpec::Core::RakeTask.new(:spec)

data/lib/rack/params.rb

@@ -1,4 +1,8 @@
 require 'rack/params/context'
+require 'rack/params/context/hash_context'
+require 'rack/params/context/array_context'
+
+require 'rack/params/connector'
 require 'rack/params/errors'
 require 'rack/params/result'
 require 'rack/params/version'
@@ -6,8 +10,8 @@ require 'rack/params/version'
 module Rack
 
   # Rack::Params provides a lightweight DSL for type coercion and validation of request parameters.
-  # @!parse extend Rack::Params::ClassMethods
   module Params
+    # @!parse extend Rack::Params::ClassMethods
 
     # @private
     def self.included(base)
@@ -15,15 +19,13 @@ module Rack
     end
 
     module ClassMethods
-      # holds options and a block when registering a validator.
       # @private
       Validator = Struct.new(:options, :code) do
-        def exec(values)
-          HashContext.new(values, options).exec(&code)
+        def exec(values, **options)
+          Rack::Params::Context.exec(values, options, &code)
         end
       end
 
-      # get the set of validators, keyed by name
       # @private
       def validators
         @_rp_validators ||= {}
@@ -56,12 +58,12 @@ module Rack
         name   = nil
       end
 
-      fail ArgumentError, "no parameters provided!" if params.nil?
+      fail "no parameters provided!" if params.nil?
       if name.nil?
-        fail ArgumentError, "no validation block was provided!" unless block_given?
-        HashContext.new(params, options).exec(&block)
+        fail "no validation block was provided!" unless block_given?
+        Rack::Params::Context.exec(params, **options, &block)
       else
-        fail ArgumentError, "no validation is registered under #{name}" unless self.class.validators.key? name
+        fail "no validation is registered under #{name}" unless self.class.validators.key? name
         self.class.validators[name].exec(params)
       end
     end
@@ -85,49 +87,5 @@ module Rack
         fail ParameterValidationError, res.errors if res.invalid?
       end
     end
-
-    # mixin for frameworks that have a {#request} method in scope
-    # make sure you `include Rack::Params` before including
-    # @!attribute [r] params
-    #   @return [Result] the validated params, including errors
-    module Connector
-      def self.included(base)
-        base.class_eval do
-          attr_reader :params
-        end
-      end
-
-      # validates {Rack::Request#params} against a validator.
-      # @overload validate(name, options = {})
-      #   @param [Symbol] name the name of a registered validator.
-      #   @param [Hash] options
-      #   @return [Result] a result hash containing the extracted keys, and any errors.
-      #   @raise [ParameterValidationError] if the parameters are invalid after validation and coercion 
-      # @overload validate(options = {}, &block)
-      #   validates the given parameters against the given block
-      #   @param [Hash] options
-      #   @yield a code block that will run in the context of a {Rack::Params::HashContext} to validate the params
-      #   @return [Result] a result hash containing the extracted keys, and any errors.
-      #   @raise [ParameterValidationError] if the parameters are invalid after validation and coercion 
-      def validate(name = nil, params = nil, options = {}, &block)
-        super(name, params || request.params, options, &block)
-      end
-
-      # validates {Rack::Request#params} against a validator, raising on errors.
-      # @overload validate!(name, options = {})
-      #   @param [Symbol] name the name of a registered validator.
-      #   @param [Hash] options
-      #   @return [Result] a valid result hash containing the extracted keys, and no errors.
-      #   @raise [ParameterValidationError] if the parameters are invalid after validation and coercion 
-      # @overload validate!(options = {}, &block)
-      #   validates the given parameters against the given block
-      #   @param [Hash] options
-      #   @yield a code block that will run in the context of a {Rack::Params::HashContext} to validate the params
-      #   @return [Result] a valid result hash containing the extracted keys, and no errors.
-      #   @raise [ParameterValidationError] if the parameters are invalid after validation and coercion 
-      def validate!(name = nil, params = nil, options = {}, &block)
-        super(name, params || request.params, options, &block)
-      end
-    end
   end
 end

data/lib/rack/params/connector.rb

@@ -0,0 +1,49 @@
+module Rack
+  module Params
+
+    # mixin for frameworks that have a {#request} method in scope
+    # make sure you `include Rack::Params` before including
+    # @!attribute [r] params
+    #   @return [Result] the validated params, including errors
+    module Connector
+      def self.included(base)
+        base.class_eval do
+          attr_reader :params
+        end
+      end
+
+      # validates {Rack::Request#params} against a validator.
+      # @overload validate(name, options = {})
+      #   @param [Symbol] name the name of a registered validator.
+      #   @param [Hash] options
+      #   @return [Result] a result hash containing the extracted keys, and any errors.
+      #   @raise [ParameterValidationError] if the parameters are invalid after validation and coercion 
+      # @overload validate(options = {}, &block)
+      #   validates the given parameters against the given block
+      #   @param [Hash] options
+      #   @yield a code block that will run in the context of a {Rack::Params::HashContext} to validate the params
+      #   @return [Result] a result hash containing the extracted keys, and any errors.
+      #   @raise [ParameterValidationError] if the parameters are invalid after validation and coercion 
+      def validate(name = nil, params = nil, options = {}, &block)
+        super(name, params || request.params, options, &block)
+      end
+
+      # validates {Rack::Request#params} against a validator, raising on errors.
+      # @overload validate!(name, options = {})
+      #   @param [Symbol] name the name of a registered validator.
+      #   @param [Hash] options
+      #   @return [Result] a valid result hash containing the extracted keys, and no errors.
+      #   @raise [ParameterValidationError] if the parameters are invalid after validation and coercion 
+      # @overload validate!(options = {}, &block)
+      #   validates the given parameters against the given block
+      #   @param [Hash] options
+      #   @yield a code block that will run in the context of a {Rack::Params::HashContext} to validate the params
+      #   @return [Result] a valid result hash containing the extracted keys, and no errors.
+      #   @raise [ParameterValidationError] if the parameters are invalid after validation and coercion 
+      def validate!(name = nil, params = nil, options = {}, &block)
+        super(name, params || request.params, options, &block)
+      end
+    end
+    
+  end
+end

data/lib/rack/params/context.rb

@@ -1,12 +1,14 @@
-require 'date'
+require 'rack/params/validator'
 
 module Rack
   module Params
 
-    # the context in which to run validation.
+    # the validator to run.
     # it contains the {#params} and {#result}, and provides methods to use in coercion.
     # @abstract To subclass, provide a {Result} constant, and methods to do coercion/validation.
-    class Context
+    class Context 
+      include Rack::Params::Validator
+
       attr_reader :options
       attr_reader :params
       attr_reader :result
@@ -15,7 +17,11 @@ module Rack
       # the actual {#result} will be this type extended by {Rack::Params::Result}
       Result = nil
 
-      # create a context with a parameter hash and options.
+      def self.exec(params, **options, &block)
+        HashContext.new(params, options).exec(&block)
+      end
+
+      # create a validator with a parameter hash and options.
       def initialize(params, options = {})
         @options = options
         @path    = options[:path]
@@ -24,193 +30,55 @@ module Rack
 
         @result = self.class::Result.new
         @result.extend ::Rack::Params::Result
-        @result.errors = Hash.new { |h, k| h[k] = [] }
+        @result.errors = ::Hash.new { |h, k| h[k] = [] }
       end
 
-      # execute the given block, in this context
+      # execute the given block, in this validator
       # @yield in the block, {self}'s methods are available.
-      # @return [Result] the result of this context's validation.
+      # @return [Result] the result of validation
       def exec(&block)
         instance_exec(&block)
         @result
       end
 
-      protected
-
-      # return a correctly typed value, given a string and a type.
-      #
-      # == valid types
-      # :symbol   :: convert value as a symbol
-      # :boolean  :: parse the following strings: "0, 1, false, f, true, t, no, n, yes, y"
-      # Symbol    ::
-      # Int       ::
-      # Float     ::
-      # Date      ::
-      # Time      ::
-      # DateTime  :: parse as the given type.
-      # Array     :: parse value as an array. default options { sep: ' ' }
-      # Hash      :: parse value as a Hash, default options { esep: ',', fsep: ':' }
-      #
-      # @param value the value to coerce, likely a string, hash or array
-      # @param type the type to coerce into
-      # @param options [Hash]
-      # @return value the coerced value
-      # @raise [ArgumentError] if coercion fails
-      def _coerce(value, type, options)
-        return nil   if value.nil?
-        return value if value.is_a?(type) rescue false
-
-        return value.to_sym if type == :symbol || type == Symbol
-
-        return Integer(value, options[:base] || 0) if type == ::Integer
-        return Float(value)                        if type == ::Float
-
-        [::Date, ::Time, ::DateTime].each do |klass|
-          return klass.parse(value) if type == klass
-        end
-
-        if type == ::Array
-          sep    = options.fetch(:sep, ',')
-
-          values = value.split(sep)
-          return Array(values)
-        end
-
-        if type == ::Hash
-          esep   = options.fetch(:esep, ',')
-          fsep   = options.fetch(:fsep, ':')
-
-          values = value.split(esep).map { |p| p.split(fsep) }
-          return ::Hash[values]
-        end
-
-        if type == ::TrueClass || type == ::FalseClass || type == :boolean
-          return false if /^(false|f|no|n|0)$/i === value
-          return true  if /^(true|t|yes|y|1)$/i === value
-          raise ArgumentError # otherwise
-        end
-
-        # default failure
-        raise ArgumentError, "unknown type #{type}"
-      end
-
-      # todo: figure this out
-      # def _validate(key, value, validation, options)
-      #   options = {} if options == true
-      # end
-
-      # recursively process parameters, so we can support validating nested
-      # parameter hashes and arrays.
+      # yields the value to the block, according to the type.
+      # @param [String] key current params path segment
+      # @param value to yield to the block
+      # @param type of value, special handling for recursible types (Hash | Array)
       #
-      # @param path [String] the current path to the recursing object, used to provide error keys
-      # @param type must be {Array} or {Hash}
-      # @return [Result] with validation results and errors
-      def _recurse(path, type, value, &block)
-        path = [@path, path].reject(&:nil?).join(".")
-
-        if type == Array
-          ArrayContext.new(value, path: path).exec(&block)
-        elsif type == Hash
-          HashContext.new(value, path: path).exec(&block)
-        else
-          fail "can not recurse into #{type}"
-        end
-      end
-    end
-
-    # the DSL for validating a hash parameter (including the top-level params hash)
-    class HashContext < Context
-      Result = Hash
-
-      # do type coercion and validation for a parameter with the given key.
-      # adds the coerced value to the result hash, or push an error.
+      # @overload _yield(key, value, type, options = {}, &block)
+      #   returns the result of yielding the value to the block
+      #   @param [Hash] options, same as {#_fetch}
+      #   @return [Array] tuple of result of yielding the value to the block, and errors
       #
-      # @see #_coerce #_coerce defines valid types for coercion.
-      # @param key the key in the hash of the parameter to validate
-      # @param type the type to coerce the value into
-      # @param options [Hash]
-      # @yield
-      #   if type is {Hash} or {Array}, passing a block will recursively
-      #   validate the coerced value, assuming the block is a new validation
-      #   context.
-      # @return the coerced value
-      def param(key, type, options = {}, &block)
-        key = key.to_s
-
-        # default and required
-        value = params[key] || options[:default]
-        raise ArgumentError, "is required" if options[:required] && value.nil?
-
-        # type cast
-        value = _coerce(value, type, options)
-
-        # validate against rules
-        # options.each { |v, vopts| _validate(key, value, v, vopts) }
-
-        # recurse if we've got a block
-        if block_given?
-          value = _recurse(key, type, value, &block)
-          result.errors.merge! value.errors
+      # @overload _yield(key, value, type = Hash | Array, options = {}, &block)
+      #   recursively validates the value through the block given, which is run
+      #   inside a suitable validation context; also merges result errors.
+      #   @param [Hash] options, same as {#initialize}
+      #   @return [Array] tuple of validated results
+      def _yield(key, value, type, **options, &block)
+        # simple types
+        unless type == ::Array || type == ::Hash
+          return super(value, **options, &block) 
         end
 
-        # return - we're good
-        result[key] = value
-      rescue ArgumentError => ex
-        path = [@path, key].reject(&:nil?).join(".")
-        result.errors[path] << ex.message
-        nil
-      end
-
-      # collect uncoerced keys from the parameter hash into the results hash.
-      # collects keys not _yet_ coerced, so it should be last in the validation block.
-      #
-      # @param key the result key under which to place the collected parameters
-      # @param options [Hash]
-      # @return the collected keys as a hash
-      def splat(key, options = {})
-        key = key.to_s
+        # recursive types
+        fail "no block provided" if block.nil?
+        path   = [@path, key].reject(&:nil?).join(".")
+        values =
+          if type == ::Array
+            Rack::Params::Context::ArrayContext.new(value, path: path).exec(&block)
+          elsif type == ::Hash
+            Rack::Params::Context::HashContext.new(value, path: path).exec(&block)
+          else
+            fail "cannot recurse into #{type}"
+          end
 
-        # every key in params that's not already in results
-        value = params.reject { |k, _| result.keys.include? k }
-        result[key] = value
+        # this is special, we merge errors
+        result.errors.merge! values.errors
+        return values
       end
     end
 
-    # the DSL for validating an array parameter
-    class ArrayContext < Context
-      Result = Array
-
-      # validate and coerce every element in the array, using the same values.
-      # equivalent to {HashContext#param} over every element.
-      #
-      # @see HashContext#param
-      # @see #_coerce #_coerce defines valid types for coercion.
-      # @param type the type to use for coercion
-      # @param options [Hash]
-      # @yield
-      #   if type is Hash or Array, passing a block will recursively
-      #   validate the coerced value, assuming the block is a new validation
-      #   context.
-      # @return the coerced value
-      def every(type, options = {}, &block)
-        params.each_with_index do |value, i|
-          begin
-            value = _coerce(value, type, options)
-            # options.each { |v, vopts| _validate(i.to_s, value, v, vopts) }
-            if block_given?
-              value = _recurse(i.to_s, type, value, &block)
-              result.errors.merge! value.errors
-            end
-
-            result[i] = value
-          rescue ArgumentError => ex
-            path = [@path, i].reject(&:nil?).join(".")
-            result.errors[path] << ex.message
-            nil
-          end
-        end
-      end
-
-    end
   end
 end

data/lib/rack/params/context/array_context.rb

@@ -0,0 +1,44 @@
+require 'rack/params/validator'
+
+module Rack
+  module Params
+    class Context
+
+      # the DSL for validating an array parameter
+      class ArrayContext < Context
+        Result = ::Array
+
+        # validate and coerce every element in the array, using the same values.
+        # equivalent to {HashContext#param} over every element.
+        #
+        # @see HashContext#param
+        # @see #_coerce #_coerce defines valid types for coercion.
+        # @param type the type to use for coercion
+        # @param options [Hash]
+        # @yield
+        #   if type is Hash or Array, passing a block will recursively
+        #   validate the coerced value, assuming the block is a new validation
+        #   context.
+        # @return the coerced value
+        def every(type, **options, &block)
+          options[:required] = true unless options.key?(:required)
+
+          params.each_with_index do |value, i|
+            begin
+              value = _coerce(value, type, options)
+              value = _yield(i.to_s, value, type, options, &block) unless block.nil?
+
+              # options.each { |v, vopts| _validate(i.to_s, value, v, vopts) }
+
+              result[i] = value
+            rescue ArgumentError => ex
+              path = [@path, i].reject(&:nil?).join(".")
+              result.errors[path] << ex.message
+              nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rack/params/context/hash_context.rb

@@ -0,0 +1,89 @@
+require 'rack/params/context'
+
+module Rack
+  module Params
+    class Context
+
+      # the DSL for validating a hash parameter (including the top-level params hash)
+      class HashContext < Context
+        Result = ::Hash
+
+        # return the value from the params hash, validating it's presence from options
+        # @param key the name of the param to fetch
+        # @param [Hash] options
+        # @option options [Any]     :default     the value to return if the param is missing
+        # @option options [Boolean] :required    will fail if key is missing from params
+        # @option options [Boolean] :allow_nil
+        #   is nil considered present? for :required?,
+        #   defaults to false, considered missing.
+        # @option options [Boolean] :allow_blank
+        #   is blank considered present? for :required?,
+        #   defaults to false, considered missing.
+        # @see #_blank?
+        def _fetch(key, options)
+          value = params.key?(key) ? params[key] : options[:default]
+          options[:required] ? _ensure(value, options) : value
+        end
+
+        # do type coercion and validation for a parameter with the given key.
+        # adds the coerced value to the result hash, or push an error.
+        #
+        # @param [String] key the key in the parameter hash
+        # @param [Hash] options
+        # @option options [Boolean] :required    will fail if key is missing from params
+        # @option options [Any]     :default     the value to return if the param is missing
+        # @option options [Boolean] :allow_nil   is nil considered present?, defaults to false, considered missing.
+        # @option options [Boolean] :allow_blank is blank (0-length string, or nil) considered present?, defaults to false, considered missing.
+        # @return the coerced value
+        #
+        # @overload param(key, type = String, options = {}, &block)
+        #   coerces the value through the block given, marking invalid on raised errors.
+        #   if yielding to the block, the :allow_nil and :allow_blank options apply equally to the result of the block
+        #   (use the `allow_nil` and `allow_falsey` options to change the validity behavoir)
+        #   @option options [Boolean] :allow_falsey is falsey considered present?, defaults to false, considered missing.
+        #   @yield to the transformation function, failure on nil, blank or ArgumentError (unless `:allow_nil` or `:allow_blank`)
+        #   @yieldparam [String|nil] value from the param hash to validate/coerce
+        #   @yieldreturn the value that's been validated/coerced
+        #   @see #_coerce #_coerce defines valid types for coercion.
+        #
+        # @overload param(key, type = Hash | Array, options = {}, &block)
+        #   recursively validates the value through the block given, which
+        #   is run in the context of a suitable validation context.
+        #   @yield
+        #     if type is {Hash} or {Array}, passing a block will recursively
+        #     validate the coerced value, assuming the block is a new validation
+        #     context. if type is not {Hash} or {Array}, raises `ArgumentError`
+        def param(key, type = String, **options, &block)
+          key   = key.to_s
+          value = _fetch(key, options)
+          value = _coerce(value, type, options)
+          value = _yield(key, value, type, options, &block) unless block.nil?
+
+          # validate against rules
+          # options.each { |v, vopts| _validate(key, value, v, vopts) }
+
+          result[key] = value
+        rescue ArgumentError => ex
+          path = [@path, key].reject(&:nil?).join(".")
+          result.errors[path] << ex.message
+          nil
+        end
+
+        # collect uncoerced keys from the parameter hash into the results hash.
+        # collects keys not _yet_ coerced, so it should be last in the validation block.
+        #
+        # @param key the result key under which to place the collected parameters
+        # @param options [Hash]
+        # @return the collected keys as a hash
+        def splat(key, options = {})
+          key = key.to_s
+
+          # every key in params that's not already in results
+          value = params.reject { |k, _| result.keys.include? k }
+          result[key] = value
+        end
+      end
+
+    end
+  end
+end

data/lib/rack/params/tasks.rake

@@ -4,7 +4,7 @@ require 'yard/rake/yardoc_task'
 
 namespace :docs do
   ROOT_DIR = `git rev-parse --show-toplevel`.strip
-  DOC_DIR  = File.join(ROOT_DIR, 'docs')
+  DOC_DIR  = File.join(ROOT_DIR, 'doc')
 
   YARD::Rake::YardocTask.new(:generate) do |yard|
     yard.options = ["--out", DOC_DIR]

data/lib/rack/params/validator.rb

@@ -0,0 +1,103 @@
+require 'date'
+
+module Rack
+  module Params
+
+    # a bunch of helpers for coercion and validation of parameter values
+    module Validator
+
+      # An object is blank if it's false, empty, or a whitespace string.
+      # For example, false, '', ' ', nil, [], and {} are all blank.
+      # #hattip rails' Object#blank?
+      # @param [Any] value to check
+      # @return true if blank, false otherwise
+      def _blank?(value)
+        value.respond_to?(:empty?) ? !!value.empty? : !value
+      end
+      
+      # return a correctly typed value, given a string and a type.
+      #
+      # == valid types
+      # :boolean    :: parse the following strings: "0, 1, false, f, true, t, no, n, yes, y"
+      # :symbol     :: parse as a symbol, (#to_sym)
+      # String      :: parse as a String, (#to_s)
+      # Int         :: parse an an int, with an optional base (from options)
+      # Float       :: parse as the given type
+      # #parse      :: parse with a parse method on type (Date, Time, etc.)
+      # Array, Hash :: Rack::QueryParser already converts these, so return them directly
+      #
+      # @param value   to coerce, likely a string, hash or array
+      # @param type    to coerce into
+      # @param options to control coercion
+      # @option options :base [Number] the base to parse into for Integer
+      # @return value the coerced value
+      # @raise [ArgumentError] if coercion fails
+      # @raise [RuntimeError]  if unsupported type given
+      def _coerce(value, type, options = {})
+        return nil if value.nil?
+        return value if value.is_a?(type) rescue false
+
+        return value.to_s if type == ::String
+        return value.to_sym if type == :symbol
+
+        return Integer(value, options[:base] || 0) if type == ::Integer
+        return Float(value)                        if type == ::Float
+
+        if type.respond_to?(:parse)
+          return type.parse(value)
+        end
+
+        if type == ::TrueClass || type == ::FalseClass || type == :boolean
+          return false if /^(false|f|no|n|0)$/i === value
+          return true  if /^(true|t|yes|y|1)$/i === value
+          raise ArgumentError, "couldn't parse as boolean" # otherwise
+        end
+
+        # default failure
+        fail "unknown type #{type}"
+      end
+
+      # todo: figure this out
+      # def _validate(key, value, validation, options)
+      #   options = {} if options == true
+      # end
+
+      # ensures value, checking for nils and blank values
+      # @see #_blank?
+      # @param value to check
+      # @param [Hash] options
+      # @option options :allow_nil [Boolean] if value is nil, return it?
+      # @option options :allow_blank [Boolean] if value is blank, return it?
+      # @raise [ArgumentError] when a value is required but not present
+      # @return the value, conforming to the options given
+      def _ensure(value, options = {})
+        # allow nil has to precede allow blank, as nil is blank
+        if options[:allow_nil] && value.nil?
+          return value
+        end
+
+        if !options[:allow_blank] && _blank?(value)
+          fail ArgumentError, "is required."
+        end
+
+        value
+      end
+
+      # yields the value to the block, with required semantics
+      # @param value to yield to the block
+      # @option options :required [Boolean] ensure value returned from block exists
+      # @option options :allow_nil [Boolean] if :required, allow nils
+      # @option options :allow_blank [Boolean] if :required, allow blank
+      # @return value after transformation
+      # @see _ensure
+      def _yield(value, **options, &block)
+        fail "no block provided" if block.nil?
+
+        value = block.call(value)
+        return options[:required] ? _ensure(value, options) : value
+      end
+
+    end
+
+  end
+end

data/lib/rack/params/version.rb

@@ -1,5 +1,5 @@
 module Rack
   module Params
-    VERSION = "0.0.1.pre5"
+    VERSION = "0.0.1.pre6"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rack-params
 version: !ruby/object:Gem::Version
-  version: 0.0.1.pre5
+  version: 0.0.1.pre6
 platform: ruby
 authors:
 - Jon Raphaelson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-01-26 00:00:00.000000000 Z
+date: 2018-02-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -147,6 +147,7 @@ files:
 - ".rspec"
 - ".travis.yml"
 - ".yardopts"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -156,10 +157,14 @@ files:
 - bin/console
 - bin/setup
 - lib/rack/params.rb
+- lib/rack/params/connector.rb
 - lib/rack/params/context.rb
+- lib/rack/params/context/array_context.rb
+- lib/rack/params/context/hash_context.rb
 - lib/rack/params/errors.rb
 - lib/rack/params/result.rb
 - lib/rack/params/tasks.rake
+- lib/rack/params/validator.rb
 - lib/rack/params/version.rb
 - rack-params.gemspec
 homepage: https://github.com/lygaret/rack-params