sinatra-param-validator 0.16.1 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78acd25fda0c630a67c5ce3e2b24a9300c70432b40621a1ebd2822e4d63a549b
-  data.tar.gz: 6ad51ab220feb9b3ec422532d1ae46bc2b812ec9969eec4e3b7a5b6b0387f4a6
+  metadata.gz: cc96ce9554cce1728ccfe8611b8a32683f59ecab0cb0c30f2048a4f36546cb85
+  data.tar.gz: 5a9a45fee8f03500085750f0af21c30e0d36c1d66dcd7c0799049435aae9cba4
 SHA512:
-  metadata.gz: 224a086b11dc650444326980951756850ae049e4f09b17dac6ae73881327ae694ca2c38f3855887300ebeeed6a9fc36d61651d61884cbe237f057d964858e6e2
-  data.tar.gz: 1b80d184a2e078f22a265cfcc3d38aa083f4cb6ad0e0850d193b5c39ef2bbe190ea87c7edbd628c9b3121472b7704367d58e9e9a8c4b357338daf14c0e70d8cf
+  metadata.gz: 87356c1bd08e3969b8e5d35709af6a18b4be740a38eedf9db3744741823fe4c00a7a494aaaece03cfe5495cd7acc149585f7eaa4036b4a36e91117063bf96fa8
+  data.tar.gz: d71e87ff1462b200e8a36a5f0d0fdd7321fa4b28356951baeba2704afa0246989c6bd95d517cb913b0bb66e2355cb332a5776c04108f7bbc1feb36d8e776047c

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [0.17.0] - 2022-07-19
+
+- `param` should return the coerced value
+- Add `transform` to alter a validated parameter
+
 ## [0.16.1] - 2022-07-19
 
 - Fix URIs in gemspec

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sinatra-param-validator (0.16.1)
+    sinatra-param-validator (0.17.0)
 
 GEM
   remote: https://rubygems.org/
@@ -85,4 +85,4 @@ DEPENDENCIES
   sinatra-param-validator!
 
 BUNDLED WITH
-   2.3.17
+   2.3.16

data/README.md

@@ -76,6 +76,9 @@ All parameters have the following validations available:
   * If this is set, all other validations are skipped if the value is nil
 * `required`
   * The parameter must be present and cannot be nil
+* `transform`
+  * Run a method against the validated parameter, allowing it to be changed
+  * Anything that responds to `to_proc` will work; procs, lambdas, symbols...
 * `in`
   * The value is in the given array / range
 * `is`
@@ -89,6 +92,41 @@ All parameters have the following validations available:
 
 * `min` / `max`
 
+### Running as a helper
+
+`param` is available as a helper in routes, and will raise `Sinatra::ParamValidator::InvalidParameterError` if validation fails.
+It will return the parsed parameter, after coercion, defaults and transformations have been applied.
+
+```ruby
+get '/page' do
+  param :a, String
+end
+```
+
+## Rules
+
+Rules work on multiple parameters:
+
+```ruby
+rule :all_or_none_of, :a, :b
+```
+
+* `all_or_none_of`
+* `any_of`
+  * At least one of the given fields must be present
+* `one_of`
+  * Only one of the given fields can be present
+
+### Running as a helper
+
+`rule` is available as a helper in routes, and will raise `Sinatra::ParamValidator::InvalidParameterError` if validation fails.
+
+```ruby
+get '/page' do
+  rule :any_of, :a, :b
+end
+```
+
 ## Custom Messages
 
 It is possible to return a custom error message when a validation fails:
@@ -113,6 +151,10 @@ It is possible to run code after a validation succeeds, by passing a block to `p
 param :number, Integer, required: true do
   # ...
 end
+
+rule :any_of, :a, :b do
+  # ...
+end
 ```
 
 If you wish to indicate a validation failure within a block, raise `Sinatra::ParameterValidator::InvalidParameterError`
@@ -126,20 +168,6 @@ param :number, Integer, required: true do |validator|
 end
 ```
 
-## Rules
-
-Rules work on multiple parameters:
-
-```ruby
-rule :all_or_none_of, :a, :b
-```
-
-* `all_or_none_of`
-* `any_of`
-  * At least one of the given fields must be present
-* `one_of`
-  * Only one of the given fields can be present
-
 ## Validator Types
 
 The default validator will raise `Sinatra::ParamValidator::ValidationFailedError` when validation fails.
@@ -149,7 +177,7 @@ There are two other provided validators, that handle failure differently:
 * `url_param`
   * will `halt 403`
 * `form`
-  * if [sinatra-flash](https://github.com/SFEley/sinatra-flash) is available, it will flash the errors and `redirect back`
+  * if [sinatra-flash](https://rubygems.org/gems/sinatra-flash) is available, it will flash the errors and `redirect back`
   * will provide a JSON object with errors to an XHR request
   * will `halt 400`
 
@@ -165,6 +193,55 @@ get '/user/:id', validate_url_param: :user_id do
 end
 ```
 
+### Form Helpers
+
+There are some general helpers for handling values after validation.
+These require the [sinatra-flash](https://rubygems.org/gems/sinatra-flash) gem.
+
+* `form_values(hash)`
+  * Set the values that will be returned by `form_value`.
+  * These will be overridden by any values flashed to the session in the `:params` hash
+* `form_value(field)`
+  * Get the form value for the given field
+* `form_error?(field = nil)`
+  * With a field: returns if that field had any validation errors
+  * Without a field: returns if any field had validation errors
+* `form_errors(field)`
+  * Get the list of validation errors for the given field
+* `invalid_feedback(field, default = nil)`
+  * Get the invalid feedback (error message) for the given field, defaulting to the default parameter.
+
+#### Usage
+
+For a form to edit something, you can define the values that the form should use:
+
+```ruby
+get '/edit/:thing' do
+  thing = #...
+  form_values thing
+end
+```
+
+This is an example form input with bootstrap styling:
+
+```html
+<form method="post" <%== 'class="was-validated"' if form_error? %>>
+  <div class="mb-3">
+    <label class="form-label" for="name">Name</label>
+    <input type="text" name="name" id="name" 
+           class="form-control <%= 'is-invalid' if form_error? :name %>"
+           value="<%= form_value :name %>">
+    <div class="invalid-feedback">
+      <%== invalid_feedback :name, 'Please provide a name.' %>
+    </div>
+  </div>
+</form>
+```
+
+When the form is submitted, validation may fail, and the page will redirect back to the edit form.
+The redirect will flash the submitted parameters.
+`form_value` will now prefer the flashed parameters over the original values for `thing`.
+
 ## Validators with parameters
 
 It is possible to define a validator with a parameter.

data/lib/sinatra/param_validator/helpers.rb

@@ -13,14 +13,15 @@ module Sinatra
         raise "Filter params failed: #{e}"
       end
 
-      def param(key, type, default: nil, message: nil, **args, &block)
+      def param(key, type, default: nil, message: nil, transform: nil, **args, &block) # rubocop:disable Metrics/ParameterLists
         parameter = Parameter.new(params[key], type, **args)
-        _update_params_hash key, parameter, default
         if parameter.valid?
+          _update_params_hash key, parameter, default, transform
           _run_block(key, block) if block
         else
           _handle_error key, message || parameter.errors
         end
+        params[key]
       rescue NameError
         raise 'Invalid parameter type'
       end
@@ -57,16 +58,18 @@ module Sinatra
         _handle_error key, e.message
       end
 
-      def _update_params_hash(key, parameter, default)
-        if params.key?(key) && !params[key].nil?
-          _set_param_to_coerced key, parameter
-        elsif !default.nil?
-          _set_param_to_default key, default
+      def _update_params_hash(key, parameter, default, transform)
+        if !params.key?(key) || params[key].nil?
+          _set_param_to_default key, default unless default.nil?
+        else
+          _set_param_to_coerced key, parameter, transform
         end
       end
 
-      def _set_param_to_coerced(key, parameter)
-        params[key] = parameter.coerced unless parameter.coerced.nil?
+      def _set_param_to_coerced(key, parameter, transform)
+        return if parameter.coerced.nil?
+
+        params[key] = transform.nil? ? parameter.coerced : transform.to_proc.call(parameter.coerced)
       end
 
       def _set_param_to_default(key, default)

data/lib/sinatra/param_validator/version.rb

@@ -2,6 +2,6 @@
 
 module Sinatra
   module ParamValidator
-    VERSION = '0.16.1'
+    VERSION = '0.17.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sinatra-param-validator
 version: !ruby/object:Gem::Version
-  version: 0.16.1
+  version: 0.17.0
 platform: ruby
 authors:
 - Rick Selby