formeze 2.1.0 → 4.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 966031b2657f2210d398a97d3c8dd6a1cc4e424e39972db1c3bad968cfe3bc8e
+  data.tar.gz: 140936f1897241dc7ee598fd8e63296d3d7918879dd263d825e68299897e1a1f
+SHA512:
+  metadata.gz: '092df6a16316cd7fb65f997e3e25e65622a1e8e112a5da8db6c56ca4146dc4485502fcc1ed7b9cb6a34e452878e3a6151a7c3c7c47e759ef7fe6349d35f5c1e4'
+  data.tar.gz: 0b4641a90d0d9e7e0cface189b699f12ebd60e94de2350a7dcbee537be6e22bd8b721587199ce3e24202ea5ccb8c1083438abd9bfa5d55538556825e08cbe0bc

data/CHANGES.md

@@ -0,0 +1,164 @@
+# 4.0.0
+
+* Removed support for older rubies. **Required ruby version is now 2.4.0**
+
+* Changed the code to use keyword arguments for options
+
+* Renamed the `when` validation option to `if`
+
+# 3.1.0
+
+* Added `'commit'` to the list of Rails form keys to ignore (#4)
+
+* Added frozen string literal comment
+
+* Extracted private constants to reduce memory allocations
+
+* Removed spec file from gem
+
+# 3.0.0
+
+* Added functionality for handling multipart form data. For example:
+
+      class ExampleForm < Formeze::Form
+        field :image, accept: 'image/jpg,image/png', maxsize: 1000
+      end
+
+  For this to work the request needs to be passed to the parse method:
+
+      ExampleForm.new.parse(request)
+
+* Removed the deprecated parse class method
+
+* Removed Ruby 1.8.7 compatibility
+
+# 2.2.0
+
+* The #fill and #parse instance methods now return self. So instead of this:
+
+      form = ExampleForm.new
+      form.parse(request.raw_post)
+
+  You can now do this:
+
+      form = ExampleForm.new.parse(request.raw_post)
+
+* Deprecated the parse class method
+
+# 2.1.1
+
+* Fixed that custom validation should not execute for optional fields with blank values
+
+# 2.1.0
+
+* Fixed that custom validation should only execute when there are no existing errors on the associated field
+
+* Removed `:word_limit` field option
+
+# 2.0.0
+
+* Added new custom validation functionality
+
+* Removed existing (undocumented) custom validation functionality
+
+* KeyError now includes an error message when raised for unexpected keys
+
+* Added #to_h form instance method
+
+* Removed `:char_limit` field option
+
+* Deprecated `:word_limit` field option (use custom validation instead)
+
+# 1.9.1
+
+* Added `:minlength` field option
+
+* Added `:maxlength` field option
+
+* Deprecated `:char_limit` field option (use `:maxlength` instead)
+
+# 1.9.0
+
+* Added `:blank` field option for specifying a null object to be used in place of blank input
+
+# 1.8.0
+
+* Added #fill instance method
+
+* Improved handling of Rails utf8/authenticity_token parameters
+
+# 1.7.0
+
+* Ruby 1.8.7 compatibility
+
+* Renamed `Formeze::UserError` to `Formeze::ValidationError`
+
+* Added #to_hash instance method
+
+# 1.6.0
+
+* Added #errors_on? instance method for checking if there are errors on a specific field
+
+* Added #errors_on instance method for accessing the errors on a specific field
+
+* Added parse class method, so instead of this:
+
+      form = ExampleForm.new
+      form.parse(request.raw_post)
+
+  You can now do this:
+
+      form = ExampleForm.parse(request.raw_post)
+
+# 1.5.1
+
+* Added `Formeze::Form` class, so forms can now be defined like this:
+
+      class ExampleForm < Formeze::Form
+      end
+
+  The previous style of setup is still supported:
+
+      class ExampleForm < SomeAncestorClass
+        Formeze.setup(self)
+      end
+
+# 1.5.0
+
+* Added #errors? instance method
+
+* Added `Formeze.scrub` method so that the scrub methods can be re-used outside field validation
+
+# 1.4.0
+
+* Added `:scrub` field option for cleaning up input data before validation
+
+# 1.3.0
+
+* Added functionality for overriding error messages via i18n
+
+* Added functionality for setting field labels globally via i18n
+
+# 1.2.0
+
+* Replaced experimental guard/halting functionality with `:defined_if` and `:defined_unless` field options
+
+# 1.1.3
+
+* Fixed early return from guard/halting conditions
+
+# 1.1.2
+
+* Fixed validation so that additional checks are skipped if the input is blank
+
+# 1.1.1
+
+* Added an error message for `Formeze::KeyError` exceptions
+
+# 1.1.0
+
+* Changed behaviour of experimental guard conditions and added halting conditions with opposite behaviour
+
+# 1.0.0
+
+* First version!

data/LICENSE.txt

@@ -0,0 +1,4 @@
+Copyright (c) 2012-2020 TIMCRAFT
+
+This is an Open Source project licensed under the terms of the LGPLv3 license.
+Please see <http://www.gnu.org/licenses/lgpl-3.0.html> for license text.

data/README.md

@@ -1,53 +1,62 @@
-formeze
-=======
+# formeze
 
+![Gem Version](https://badge.fury.io/rb/formeze.svg)
+![Build Status](https://github.com/readysteady/formeze/workflows/Test/badge.svg)
 
-A little library for handling form data/input.
+Ruby gem for validating form data.
 
 
-Motivation
-----------
+## Motivation
 
 Most web apps built for end users will need to process url-encoded form data.
 Registration forms, profile forms, checkout forms, contact forms, and forms
-for adding/editing application specific data. As developers we would like to
-process this data safely, to minimise the possibility of security holes
-within our application that could be exploited. Formeze adopts the approach
-of being "strict by default", forcing the application code to be explicit in
-what it accepts as input.
+for adding/editing application specific data.
 
+As developers we would like to process this data safely, to minimise the
+possibility of security holes within our application that could be exploited.
+Formeze adopts the approach of being "strict by default", forcing the application
+code to be explicit in what it accepts as input.
 
-Installation
-------------
 
-```
-$ gem install formeze
-```
+## Install
+
+Using Bundler:
+
+    $ bundle add formeze
 
+Using RubyGems:
 
-Example usage
--------------
+    $ gem install formeze
+
+
+## Usage
 
 Here is a minimal example, which defines a form with a single field:
 
 ```ruby
+require 'formeze'
+
 class ExampleForm < Formeze::Form
   field :title
 end
 ```
 
-This form can then be used to parse and validate input data like this:
+You can then parse and validate form data in Rails or Sinatra like this:
 
 ```ruby
-form = ExampleForm.new
+form = ExampleForm.new.parse(request)
 
-form.parse('title=Title')
-
-form.title  # => "Title"
+if form.valid?
+  # do something with form data
+else
+  # display form.errors to user
+end
 ```
 
+Formeze will automatically ignore the Rails "utf8" and "authenticity_token" parameters.
+
 If you prefer not to inherit from the `Formeze::Form` class then you can
-instead call the `Formeze.setup` method like this:
+instead call the `Formeze.setup` method on your classes like this:
 
 ```ruby
 class ExampleForm
@@ -62,27 +71,23 @@ methods but will otherwise leave the object untouched (i.e. you can define
 your own initialization logic).
 
 
-Detecting errors
-----------------
+## Validation errors
 
 Formeze distinguishes between validation errors (which are expected in the
 normal running of your application), and key/value errors (which most likely
-indicate either developer error, or form tampering).
-
-For the latter case, the `parse` method that formeze provides will raise a
-`Formeze::KeyError` or a `Formeze::ValueError` exception if the structure of
-the form data does not match the field definitions.
+indicate either developer error, or form tampering). For the latter case,
+the `parse` method that formeze provides will raise a `Formeze::KeyError`
+or a `Formeze::ValueError` exception if the structure of the form data
+does not match the field definitions.
 
 After calling `parse` you can check that the form is valid by calling the
-`#valid?` method. If it isn't you can call the `errors` method which will
-return an array of error messages to display to the end user.
-
-You can also use `errors_on?` and `errors_on` to check for and select error
+`valid?` method. If it isn't you can call the `errors` method which will
+return an array of error messages to display to the end user. You can also
+use the `errors_on?` and `errors_on` methods to check for and select error
 messages specific to a single field.
 
 
-Field options
--------------
+## Field options
 
 By default fields cannot be blank, they are limited to 64 characters,
 and they cannot contain newlines. These restrictions can be overridden
@@ -106,9 +111,9 @@ is not required, i.e. the value of the field can be blank/empty. For example:
 field :title, required: false
 ```
 
-To make it easy to integrate with your application you might want to return
-a different value for blank fields, such as nil, zero, or a "null" object.
-Use the `blank` option to specify this behaviour. For example:
+You might want to return a different value for blank fields, such as nil,
+zero, or a "null" object. Use the `blank` option to specify this behaviour.
+For example:
 
 ```ruby
 field :title, required: false, blank: nil
@@ -154,18 +159,14 @@ option to handle the case where the checkbox is unchecked. For example:
 field :accept_terms, values: %w(true), key_required: false
 ```
 
-Sometimes you'll have a field with multiple values. A multiple select input,
-a set of checkboxes. For this case you can specify the `multiple` option to
-allow multiple values. For example:
+Sometimes you'll have a field with multiple values, such as a multiple select
+input, or a set of checkboxes. For this case you can specify the `multiple`
+option, for example:
 
 ```ruby
 field :colour, multiple: true, values: Colour.keys
 ```
 
-Note that unlike all the other examples so far, reading the attribute
-that corresponds to this field will return an array of strings instead
-of a single string.
-
 Sometimes you'll only want the field to be defined if some condition is true.
 The condition may depend on the state of other form fields, or some external
 state accessible from the form object. You can do this by specifying either
@@ -210,8 +211,22 @@ Custom scrub methods can be defined by adding a symbol/proc entry to the
 `Formeze.scrub_methods` hash.
 
 
-Custom validation
------------------
+## Multipart form data
+
+For file fields you can specify the `accept` and `maxsize` options, for example:
+
+```ruby
+class ExampleForm < Formeze::Form
+  field :image, accept: 'image/jpg,image/png', maxsize: 1000
+end
+```
+
+For this to work you need to make sure your application includes the
+[mime-types gem](https://rubygems.org/gems/mime-types), and that the
+form is submitted with the multipart/form-data mime type.
+
+
+## Custom validation
 
 You may need additional validation logic beyond what the field options
 described above provide, such as validating the format of a field without
@@ -243,16 +258,16 @@ class ExampleForm < Formeze::Form
 end
 ```
 
-Specify the `when` option with a proc to peform the validation conditionally.
+Specify the `if` option with a proc to peform the validation conditionally.
 Similar to the `defined_if` and `defined_unless` field options, the proc is
 evaluated in the scope of the form instance. For example:
 
 ```ruby
 class ExampleForm < Formeze::Form
-  field :business_name, :defined_if => :business_account?
-  field :vat_number, :defined_if => :business_account?
+  field :business_name, defined_if: :business_account?
+  field :vat_number, defined_if: :business_account?
 
-  validates :vat_number, :when => :business_account? do
+  validates :vat_number, if: :business_account? do
     # ...
   end
 
@@ -279,7 +294,7 @@ class ExampleForm < Formeze::Form
 
   validates :email, &EmailAddress.method(:valid?)
 
-  validates :password_confirmation, :error => :does_not_match do
+  validates :password_confirmation, error: :does_not_match do
     password_confirmation == password
   end
 end
@@ -291,49 +306,11 @@ key does not exist. The error for the password_confirmation field validation
 would include the value of the `formeze.errors.does_not_match` I18n key.
 
 
-Rails usage
------------
-
-This is the basic pattern for using a formeze form in a Rails controller:
-
-```ruby
-form = SomeForm.parse(request.raw_post)
-
-if form.valid?
-  # do something with form data
-else
-  # display form.errors to user
-end
-```
-
-Formeze will automatically ignore the "utf8" and "authenticity_token"
-parameters that Rails uses.
-
-
-Sinatra usage
--------------
-
-Using formeze with sinatra is similar, the only difference is that there is
-no raw_post method on the request object so the body has to be read directly:
-
-```ruby
-form = SomeForm.parse(request.body.read)
-
-if form.valid?
-  # do something with form data
-else
-  # display form.errors to user
-end
-```
-
-
-Integration with I18n
----------------------
+## I18n integration
 
 Formeze integrates with [I18n](http://edgeguides.rubyonrails.org/i18n.html)
 so that you can define custom error messages and field labels within your
 locales (useful both for localization, and when working with designers).
-
 For example, here is how you would change the "required" error message
 (which defaults to "is required"):
 

data/formeze.gemspec

@@ -1,15 +1,20 @@
 Gem::Specification.new do |s|
   s.name = 'formeze'
-  s.version = '2.1.0'
+  s.version = '4.0.0'
+  s.license = 'LGPL-3.0'
   s.platform = Gem::Platform::RUBY
   s.authors = ['Tim Craft']
   s.email = ['mail@timcraft.com']
-  s.homepage = 'http://github.com/timcraft/formeze'
-  s.description = 'A little library for handling form data/input'
+  s.homepage = 'https://github.com/readysteady/formeze'
+  s.description = 'Ruby gem for validating form data'
   s.summary = 'See description'
-  s.files = Dir.glob('{lib,spec}/**/*') + %w(README.md Rakefile.rb formeze.gemspec)
-  s.add_development_dependency('rake', ['>= 0.9.3'])
-  s.add_development_dependency('i18n', ['~> 0.6.0'])
-  s.add_development_dependency('minitest', ['>= 4.2.0']) if RUBY_VERSION == '1.8.7'
+  s.files = Dir.glob('lib/**/*.rb') + %w(CHANGES.md LICENSE.txt README.md formeze.gemspec)
+  s.required_ruby_version = '>= 2.4.0'
   s.require_path = 'lib'
+  s.metadata = {
+    'homepage' => 'https://github.com/readysteady/formeze',
+    'source_code_uri' => 'https://github.com/readysteady/formeze',
+    'bug_tracker_uri' => 'https://github.com/readysteady/formeze/issues',
+    'changelog_uri' => 'https://github.com/readysteady/formeze/blob/master/CHANGES.md'
+  }
 end