rack-params 0.0.1.pre3 → 0.0.1.pre5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9639d1c1bf66f13870bb654b66e08daf47b83b0a
-  data.tar.gz: a1f5b916ef01a61473ec7846d61bd2b81868ecb3
+  metadata.gz: 1007badc8d33a5465e1d7facda42c81901f4b5ad
+  data.tar.gz: a0d6fb178dc571d748ee5bb452db6a79502c8b15
 SHA512:
-  metadata.gz: 9b760ac7d1b02b4f43c81af56220c503301eaf876a1fb0b7dc8f2dd6b21183042a6752c6c462dbfe48fc8a33b039fb872cc5bdbabd1047b5201ff807d600282e
-  data.tar.gz: 75fb7462ecb7f70e145b422ea76b26f673f20f7543a7b31cbb444270b26332c6481b3e991e2905eda3fa18d98e679fd0657ef70ed25aab8dd504b977c8a2a3ad
+  metadata.gz: 6f9d9e7469c1855f94b40b151c27a1d07ea1872d1c1c0dbd81addd5ead29dfae38a91df31af3378498b15a78e2a94f2cbb3809c38059bbf0a0fb3ffe8a677cf2
+  data.tar.gz: ac8475ffbc12725fb09b60890a225baa00037d9a37ee8c77e6fb8b5e0fb110a8443d11c27c68e87b9bc324c00b759c9bc5bd4a7621965ba82c67ed6fe624f77a

data/.gitignore

@@ -2,7 +2,7 @@
 /.yardoc
 /_yardoc/
 /coverage/
-/doc/
+/docs/
 /pkg/
 /spec/reports/
 /tmp/

data/.yardopts

@@ -0,0 +1,3 @@
+--no-private
+--protected
+--embed-mixins

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at jon@accidental.cc. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/README.md

@@ -108,7 +108,7 @@ Or install it yourself as:
 
 ## Usage
 
-**[RDoc @ master - Rack::Params](http://www.rudydoc.info/github/lygaret/master)**
+**[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.

data/Rakefile

@@ -1,7 +1,16 @@
+# drop the lib directory into the load path
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "coveralls/rake/task"
 
+import(*Dir.glob("./lib/rack/params/**/*.rake"))
+
+CLOBBER << "docs"
+CLOBBER << "coverage"
+
 RSpec::Core::RakeTask.new(:spec)
 Coveralls::RakeTask.new
 

data/lib/rack/params/context.rb

@@ -3,11 +3,19 @@ require 'date'
 module Rack
   module Params
 
+    # the context in which to run validation.
+    # 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
       attr_reader :options
       attr_reader :params
       attr_reader :result
 
+      # the structure of the result - eg. {} or [].
+      # the actual {#result} will be this type extended by {Rack::Params::Result}
+      Result = nil
+
+      # create a context with a parameter hash and options.
       def initialize(params, options = {})
         @options = options
         @path    = options[:path]
@@ -19,11 +27,35 @@ module Rack
         @result.errors = Hash.new { |h, k| h[k] = [] }
       end
 
+      # execute the given block, in this context
+      # @yield in the block, {self}'s methods are available.
+      # @return [Result] the result of this context's 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
@@ -57,17 +89,24 @@ module Rack
           return true  if /^(true|t|yes|y|1)$/i === value
           raise ArgumentError # otherwise
         end
-      rescue ArgumentError => ex
-        fail InvalidParameterError, ex.message
-      end
 
-      def _validate(name, value, validation, options)
-        options = {} if options == true
-        # what to do...
+        # default failure
+        raise ArgumentError, "unknown type #{type}"
       end
 
-      def _recurse(name, type, value, &block)
-        path = [@path, name].reject(&:nil?).join(".")
+      # 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.
+      #
+      # @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)
@@ -79,65 +118,95 @@ module Rack
       end
     end
 
-    # the DSL when validating a hash parameter (including the top-level params hash)
-
+    # the DSL for validating a hash parameter (including the top-level params hash)
     class HashContext < Context
       Result = Hash
 
-      def param(name, type, options = {}, &block)
-        name = name.to_s
+      # do type coercion and validation for a parameter with the given key.
+      # adds the coerced value to the result hash, or push an error.
+      #
+      # @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[name] || options[:default]
-        raise InvalidParameterError, "is required" if options[:required] && value.nil?
+        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(name, value, v, vopts) }
+        # options.each { |v, vopts| _validate(key, value, v, vopts) }
 
         # recurse if we've got a block
         if block_given?
-          value = _recurse(name, type, value, &block)
+          value = _recurse(key, type, value, &block)
           result.errors.merge! value.errors
         end
 
         # return - we're good
-        result[name] = value
-      rescue InvalidParameterError => ex
-        path = [@path, name].reject(&:nil?).join(".")
+        result[key] = value
+      rescue ArgumentError => ex
+        path = [@path, key].reject(&:nil?).join(".")
         result.errors[path] << ex.message
+        nil
       end
 
-      def splat(name, options = {}, &block)
-        name = name.to_s
+      # 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[name] = value
+        result[key] = value
       end
     end
 
-    # the DSL when validating an array parameter
+    # the DSL for validating an array parameter
     class ArrayContext < Context
       Result = Array
 
-      # validate and coerce every element in the array to the type/options/block given
+      # 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) }
+            # 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 InvalidParameterError => ex
+          rescue ArgumentError => ex
             path = [@path, i].reject(&:nil?).join(".")
             result.errors[path] << ex.message
+            nil
           end
         end
       end

data/lib/rack/params/errors.rb

@@ -1,7 +1,13 @@
 module Rack
   module Params
 
+    # raised on {Rack::Params#validate!} failure
     class ParameterValidationError < StandardError
+
+      # @!attribute [r] errors
+      #   a hash of errors discovered during parameter coercion and validation.
+      #   keys are dotted paths from the parameter hash.
+      #   @return [Hash] a hash of errors
       attr_accessor :errors
 
       def initialize(errors)
@@ -10,9 +16,5 @@ module Rack
       end
     end
 
-    class InvalidParameterError < StandardError
-      attr_accessor :name, :type, :options
-    end
-
   end
 end

data/lib/rack/params/result.rb

@@ -1,15 +1,20 @@
 module Rack
   module Params
+
+    # a mixin for validation results, to include errors
     module Result
       attr_accessor :errors
       
+      # is the result valid, meaning it has no errors?
       def valid?
         errors.length == 0
       end
 
+      # is the result invalid, meaning it has some errors?
       def invalid?
         not valid?
       end
+
     end
   end
 end

data/lib/rack/params/tasks.rake

@@ -0,0 +1,28 @@
+require 'tmpdir'
+require 'yard'
+require 'yard/rake/yardoc_task'
+
+namespace :docs do
+  ROOT_DIR = `git rev-parse --show-toplevel`.strip
+  DOC_DIR  = File.join(ROOT_DIR, 'docs')
+
+  YARD::Rake::YardocTask.new(:generate) do |yard|
+    yard.options = ["--out", DOC_DIR]
+  end
+
+  desc "publish documentation to gh-pages"
+  task :publish do
+    Dir.mktmpdir('docs-publish') do |tmpdir| 
+      `git clone "#{ROOT_DIR}" "#{tmpdir}"`
+      Dir.chdir(tmpdir) do |cwd|
+        `git checkout gh-pages`
+        `rm -rf *`
+        `cp -R "#{DOC_DIR}"/* "#{tmpdir}/"`
+        `git add .`
+        `git commit -am 'published | #{Time.now}'`
+        `git push origin gh-pages`
+      end
+    end
+    `git push origin gh-pages`
+  end
+end

data/lib/rack/params/version.rb

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

data/lib/rack/params.rb

@@ -4,28 +4,52 @@ require 'rack/params/result'
 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
+
+    # @private
     def self.included(base)
       base.extend(ClassMethods)
     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)
         end
       end
 
+      # get the set of validators, keyed by name
+      # @private
       def validators
         @_rp_validators ||= {}
       end
 
+      # register a Validator with the given options and block.
+      # the validator can be used in #validate method by providing the name.
       def validator(name, options = {}, &code)
         validators[name] = Validator.new(options, code)
       end
     end
 
-    # validate request.params
+    # validate the given parameters
+    # @overload validate(name, params, options = {})
+    #   validates the given parameters against the named validator
+    #   @param [Symbol] name the name of a registered validator.
+    #   @param [Hash] params the parameter hash to validate
+    #   @param [Hash] options
+    #   @return [Result] a result hash containing the extracted keys, and errors.
+    # @overload validate(params, options = {}, &block)
+    #   validates the given parameters against the given block
+    #   @see Rack::Params::HashContext
+    #   @param [Hash] params the parameter hash to validate
+    #   @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 errors.
     def validate(name = nil, params = nil, options = {}, &block)
       if params.nil? && (name.class <= Hash)
         params = name
@@ -42,14 +66,30 @@ module Rack
       end
     end
 
+    # {include:#validate}
+    # @overload validate!(name, params, options = {})
+    #   @param [Symbol] name the name of a registered validator.
+    #   @param [Hash] params the parameter hash to validate
+    #   @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!(params, options = {}, &block)
+    #   validates the given parameters against the given block
+    #   @param [Hash] params the parameter hash to validate
+    #   @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)
       validate(name, params, options, &block).tap do |res|
         fail ParameterValidationError, res.errors if res.invalid?
       end
     end
 
-    # secondary mixin for frameworks that put `request` in the scope
-
+    # 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
@@ -57,9 +97,37 @@ module Rack
         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/rack-params.gemspec

@@ -24,11 +24,10 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.16"
   spec.add_development_dependency "rake", "~> 10.0"
-
   spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency 'coveralls'
-  spec.add_development_dependency 'simplecov'
-  spec.add_development_dependency 'simplecov-console'
-
+  spec.add_development_dependency "yard"
+  spec.add_development_dependency "coveralls"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "simplecov-console"
   spec.add_development_dependency "byebug", "~> 9.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rack-params
 version: !ruby/object:Gem::Version
-  version: 0.0.1.pre3
+  version: 0.0.1.pre5
 platform: ruby
 authors:
 - Jon Raphaelson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-01-23 00:00:00.000000000 Z
+date: 2018-01-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: coveralls
   requirement: !ruby/object:Gem::Requirement
@@ -132,6 +146,8 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- ".yardopts"
+- CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -143,6 +159,7 @@ files:
 - lib/rack/params/context.rb
 - lib/rack/params/errors.rb
 - lib/rack/params/result.rb
+- lib/rack/params/tasks.rake
 - lib/rack/params/version.rb
 - rack-params.gemspec
 homepage: https://github.com/lygaret/rack-params