form_input 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d7eb22ab0a9fbdbf797fd70548c4caed7201b4e7
-  data.tar.gz: d8fd5dbc4f0e7a10238aedddb889c37163e419f6
+  metadata.gz: 4014e07ca32e3c7a76ee15db0dfe478a4103d123
+  data.tar.gz: 83224f22dc199d2a3f1bf4d46011f616195d33ca
 SHA512:
-  metadata.gz: 5d8ccd8693068596ca26d4d6b15ddfbd5434b558062de2371a154c1b5e562712792065ba4ec32bc937bcd4870cac1a4f4bab4e428409f02d75303d8707c9e9ad
-  data.tar.gz: 7df1a5feca9a80307e1f1fbeb6f5a1e840775743cf96136a45e723a7cd434117563b297d57264cb5169dab8534cc125ea5af3a0009a99cb6123d4e7ce4024946
+  metadata.gz: 82f8812fbd77215e7a058f1585bc7b2ee2a5082215d4247ae865b8ced6e2c739c39e836741482ebf4cb089fe57b6c330f8b19726d8998ed8cfca48910faf92ba
+  data.tar.gz: e2e6853f4eb58193d11aa22696164844130c5c653df6b872372a40bfa1d790a8b61cf45bd287046cf7c375c14326709c49d907ba51e5779f0d3a72ad9ff12152

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+= 1.2.0
+
+ * Few changes for easier import and export of JSON payloads:
+   * The import and the new from_data methods now support numeric, boolean, and nil values natively.
+   * Added to_data method which creates a hash of all non-nil parameters.
+
 = 1.1.0
 
  * Added report! methods for late reporting of the most fundamental errors.

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2015-2018 Patrik Rak (patrik@raxoft.cz)
+Copyright (c) 2015-2019 Patrik Rak (patrik@raxoft.cz)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -86,6 +86,7 @@ Sounds cool enough? Then read on.
   * [Errors and Validation](#errors-and-validation)
   * [Using Forms](#using-forms)
   * [URL Helpers](#url-helpers)
+  * [JSON Helpers](#json-helpers)
   * [Form Helpers](#form-helpers)
   * [Extending Forms](#extending-forms)
   * [Parameter Options](#parameter-options)
@@ -798,13 +799,22 @@ to include parts of the URL as the form input:
   end
 ```
 
+Similarly, you want to use `import` when feeding form input with JSON data (see [JSON Helpers](#json-helpers) for details):
+
+``` ruby
+  post '/api/v1/contact' do
+    form = ContactForm.new.import( json_data )
+  end
+```
+
 If you are worried that you might make a mistake,
-you can use one of the three helper shortcuts
+you can use one of the four helper shortcuts
 which make it easier to remember which one to use when:
 
 ``` ruby
   form = ContactForm.from_request( request )     # Like new.import, for Rack request with external values.
   form = ContactForm.from_params( params )       # Like new.import, for params hash of external values.
+  form = ContactForm.from_data( json_data )      # Like new.import, for JSON hash of external values.
   form = ContactForm.from_hash( some_hash )      # Like new.set, for hash of internal values.
 ```
 
@@ -1254,7 +1264,7 @@ regardless of if it comes from a form post or from the URL query string.
 It is therefore quite natural that the `FormInput` provides helpers for generating
 URL query strings as well in addition to helpers used for form creation.
 
-You can get a hash of filled parameters suitable for use in the URL query by using the `url_params` method,
+You can get a hash of filled parameters suitable for use in the URL query by using the `url_params` (AKA `to_params`) method,
 or get them combined into the URL query string by using the `url_query` method.
 Note that the `url_params` result differs considerably from the result of the `to_hash` method,
 as it uses parameter code rather than name for keys and their external representation for the values:
@@ -1324,6 +1334,74 @@ Finally, if you do not like the idea of parameter arrays in your URLs, you can u
 Just note that none of the standard array parameter validations apply in this case,
 so make sure to apply your own validations using the `:check` callback if you need to.
 
+### JSON Helpers
+
+The `Form Input` can also help a great deal with validating JSON data commonly used in REST API endpoints.
+There are two methods which are quite useful in this case, `from_data` and `to_data`.
+The former imports the data from an external input hash,
+which may contain data in either internal or external form,
+while the latter creates the hash containing the data in their canonic internal form.
+
+When you create a form input from request or params, the external parameter values are always strings.
+But in case of JSON data, the values can be also numbers, booleans or `nil`.
+Fortunately, the `import` and `from_data` methods can deal with such input as well.
+The only difference is that the [input filter](#input-filter) is not run in such case.
+The [input transform](#input-transform) is run as usual,
+and so are all the [validation methods](#errors-and-validation).
+
+Among other things this means that you can declare a parameter as integer using the `INTEGER_ARGS` macro,
+and pass in the value as either string or integer, and you end up with integer in both cases, which is pretty convenient.
+
+``` ruby
+  class NumericInput < FormInput
+    param :int, INTEGER_ARGS
+    param :float, FLOAT_ARGS
+  end
+
+  NumericInput.from_data( int: '10', float: 3.0 ).to_data   # { int: 10, float: 3.0 }
+  NumericInput.from_data( int: 10, float: '3.0' ).to_data   # { int: 10, float: 3.0 }
+```
+
+Another difference when dealing with JSON data is that
+the empty strings have completely different significance than in case of web forms.
+For this reason, the result of the `to_data` method includes even empty strings, arrays, and hashes
+(unlike the `to_hash` and `to_params` methods).
+The `nil` values are still filtered out, though.
+
+``` ruby
+  class OptionalInput < FormInput
+    param :string
+    array :array
+    hash :hash
+  end
+
+  OptionalInput.from_data( string: '' ).to_data     # { string: '' }
+  OptionalInput.from_data( array: [] ).to_data      # { array: [] }
+  OptionalInput.from_data( hash: {} ).to_data       # { hash: {} }
+```
+
+The whole JSON processing may in the end look something like this:
+
+``` ruby
+  require 'oj'
+  def json_data
+    data = Oj.load( request.body, symbolize_keys: true )
+    halt( 422, 'Invalid data' ) unless Hash === data
+    data
+  rescue Oj::Error
+    halt( 422, 'Invalid JSON' )
+  end
+
+  post '/api/v1/contact' do
+    input = ContactForm.from_data( json_data )
+    halt( 422, "Invalid data: #{input.error_messages.first}" ) unless input.valid?
+    # Somehow use the input.
+    Contact.create( input.to_data )
+  end
+```
+
+Not bad for having completely validated and converted input data, is it?
+
 ### Form Helpers
 
 It may come as a surprise, but `FormInput` provides no helpers for creating HTML tags.
@@ -3178,7 +3256,7 @@ Thanks for that.
 
 ## Credits
 
-Copyright &copy; 2015-2016 Patrik Rak
+Copyright &copy; 2015-2019 Patrik Rak
 
 Translations contributed by
 Maroš Rovňák (Slovak)

data/lib/form_input/core.rb

@@ -742,6 +742,7 @@ class FormInput
     def from_params( params )
       new.import( params )
     end
+    alias from_data from_params
 
     # Create new form from hash with internal values.
     def from_hash( hash )
@@ -821,6 +822,10 @@ class FormInput
       # The validation done later ensures that the keys are valid, within range,
       # and that only flat hashes are allowed.
       Hash[ value.map{ |k, v| [ ( Integer( k, 10 ) rescue k ), sanitize_value( v, filter ) ] } ]
+    when Numeric, TrueClass, FalseClass, NilClass
+      # For convenience of importing JSON payloads, allow each of these simple scalar types as they are.
+      # The validation done later will ensure that the type class matches the parameter.
+      value
     else
       fail TypeError, "unexpected parameter type"
     end
@@ -878,7 +883,8 @@ class FormInput
   end
 
   # Return all non-empty parameters as a hash.
-  # See also url_params, which creates a hash suitable for url output.
+  # See also #to_data, which creates a hash of non-nil parameters,
+  # and #url_params, which creates a hash suitable for url output.
   def to_hash
     result = {}
     filled_params.each{ |x| result[ x.name ] = x.value }
@@ -886,6 +892,16 @@ class FormInput
   end
   alias to_h to_hash
 
+  # Return all non-nil parameters as a hash.
+  # Note that the keys are external names of the parameters (should they differ),
+  # so the keys created by `from_data(data).to_data` remain consistent.
+  # See also #to_hash, which creates a hash of non-empty parameters.
+  def to_data
+    result = {}
+    params.each{ |x| result[ x.code ] = x.value unless x.value.nil? }
+    result
+  end
+
   # Convert parameters to names and fail if we encounter unknown one.
   def validate_names( names )
     names.flatten.map do |name|
@@ -1077,6 +1093,7 @@ class FormInput
     result
   end
   alias url_parameters url_params
+  alias to_params url_params
 
   # Create string containing URL query from all current non-empty parameters.
   def url_query

data/lib/form_input/version.rb

@@ -3,7 +3,7 @@
 class FormInput
   module Version
     MAJOR = 1
-    MINOR = 1
+    MINOR = 2
     PATCH = 0
     STRING = [ MAJOR, MINOR, PATCH ].join( '.' ).freeze
   end

data/test/test_core.rb

@@ -459,6 +459,7 @@ describe FormInput do
       arr: [ "a", "b" ],
       hsh: { "1" => "2", "3" => "4" },
     }
+    f.url_params.should == f.to_params
     f.url_params.should == {
       str: "1.5",
       int: "1",
@@ -485,6 +486,7 @@ describe FormInput do
       time: "e",
       bool: false,
     }
+    f.url_params.should == f.to_params
     f.url_params.should == {
       str: "a",
       int: "0",
@@ -1184,14 +1186,44 @@ describe FormInput do
   end
 
   should 'reject unexpected values in request input' do
-    ->{ TestForm.new.import( q: "", opts: [], on: {} ) }.should.not.raise
-    ->{ TestForm.new.import( q: [], opts: {}, on: "" ) }.should.not.raise
-    ->{ TestForm.new.import( q: {}, opts: "", on: [] ) }.should.not.raise
-    ->{ TestForm.new.import( q: 1 ) }.should.raise TypeError
+    ->{ TestForm.new.import( q: "", opts: [], on: {} ).valid?(:query).should.be.false }.should.not.raise
+    ->{ TestForm.new.import( q: [], opts: {}, on: "" ).valid?(:query).should.be.false }.should.not.raise
+    ->{ TestForm.new.import( q: {}, opts: "", on: [] ).valid?(:query).should.be.false }.should.not.raise
+    ->{ TestForm.new.import( q: 1 ).valid?(:query).should.be.false }.should.not.raise
+    ->{ TestForm.new.import( q: true ).valid?(:query).should.be.false }.should.not.raise
+    ->{ TestForm.new.import( q: false ).valid?(:query).should.be.false }.should.not.raise
+    ->{ TestForm.new.import( q: nil ).valid?(:query).should.be.false }.should.not.raise
     ->{ TestForm.new.import( q: :x ) }.should.raise TypeError
     ->{ TestForm.new.import( q: TestForm ) }.should.raise TypeError
   end
 
+  should 'support importing and exporting JSON payloads without modification' do
+    data = {
+      q: 'x',
+      email: 'foo@bar.com',
+      age: 10,
+      rate: 0.5,
+      text: '',
+      # password: nil,
+      opts: [],
+      on: {},
+    }
+    f = TestForm.from_data(data)
+    f.to_data.should == data
+
+    f = TestForm.from_data(data.merge(password: nil))
+    f.to_data.should == data
+
+    f.to_hash.should == {
+      query: 'x',
+      email: 'foo@bar.com',
+      age: 10,
+      rate: 0.5,
+    }
+    f.valid?(:age).should.be.true	# has filter and correct class
+    f.valid?(:rate).should.be.false	# has no filter and class
+  end
+
   should 'make it easy to create URLs' do
     f = TestForm.new( query: "x", opts: [ 0, 0, 1 ], on: { 0 => 1 }, age: 10, email: nil, password: "", text: " " )
     f.url_params.should == { q: "x", age: "10", text: " ", opts: [ "0", "0", "1" ], on: { "0" => "1" } }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: form_input
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Patrik Rak
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-03-06 00:00:00.000000000 Z
+date: 2019-06-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack