formeze 1.0.0

data/README.md

@@ -0,0 +1,133 @@
+Formeze: A little library for defining classes to handle form data/input
+========================================================================
+
+
+Motivation
+----------
+
+Most web apps built for end users will need to process urlencoded 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.
+
+
+Example usage
+-------------
+
+Forms are just "plain old ruby objects". Calling `Formeze.setup` will include
+some class methods and instance methods, but will otherwise leave the object
+untouched (i.e. you can define your own initialization). Here is a minimal
+example, which defines a form with a single "title" field:
+
+    class ExampleForm
+      Formeze.setup(self)
+
+      field :title
+    end
+
+
+This form can then be used to parse and validate form/input data as follows:
+
+    form = ExampleForm.new
+
+    form.parse('title=Title')
+
+    form.title  # => "Title"
+
+
+Detecting errors
+----------------
+
+Formeze distinguishes between user 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.
+
+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 user.
+
+
+Field options
+-------------
+
+By default fields cannot be blank, they are limited to 64 characters,
+and they cannot contain newlines. These restrictions can be overrided
+by setting various field options.
+
+Defining a field without any options works well for a simple text input.
+If the default character limit is too big or too small you can override
+it by setting the `char_limit` option. For example:
+
+    field :title, char_limit: 200
+
+
+If you are dealing with textareas (i.e. multiple lines of text) then you can
+set the `multiline` option to allow newlines. For example:
+
+    field :description, char_limit: 500, multiline: true
+
+
+Error messages will include the field label, which by default is set to the
+field name, capitalized, and with underscores replace by spaces. If you want
+to override this, set the `label` option. For example:
+
+    field :twitter, label: 'Twitter Username'
+
+
+If you want to validate that the field value matches a specific pattern you
+can specify the `pattern` option. This is useful for validating things with
+well defined formats, like numbers. For example:
+
+    field :number, pattern: /\A[1-9]\d*\z/
+
+    field :card_security_code, char_limit: 5, value: /\A\d+\z/
+
+
+If you want to validate that the field value belongs to a set of predefined
+values then you can specify the `values` option. This is useful for dealing
+with input from select boxes, where the values are known upfront. For example:
+
+    field :card_expiry_month, values: (1..12).map(&:to_s)
+
+
+The `values` option is also useful for checkboxes. Specify the `key_required`
+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:
+
+    field :colour, multiple: true, values: Colour.keys
+
+
+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.
+
+
+Rails usage
+-----------
+
+This is the basic pattern for using a formeze form in a rails controller:
+
+    form = SomeForm.new
+    form.parse(request.raw_post)
+
+    if form.valid?
+      # do something with form data
+    else
+      # display form.errors to user
+    end
+
+
+Formeze will automatically define optional "utf8" and "authenticity_token"
+fields on every form so that you don't have to specify those manually.

data/Rakefile.rb

@@ -0,0 +1,7 @@
+require 'rake/testtask'
+
+task :default => :test
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['spec/*_spec.rb']
+end

data/formeze.gemspec

@@ -0,0 +1,12 @@
+Gem::Specification.new do |s|
+  s.name = 'formeze'
+  s.version = '1.0.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 defining classes to handle form data/input'
+  s.summary = 'See description'
+  s.files = Dir.glob('{lib,spec}/**/*') + %w(README.md Rakefile.rb formeze.gemspec)
+  s.require_path = 'lib'
+end

data/lib/formeze.rb

@@ -0,0 +1,232 @@
+require 'cgi'
+
+module Formeze
+  class Label
+    def initialize(name)
+      @name = name
+    end
+
+    def to_s
+      @name.to_s.tr('_', ' ').capitalize
+    end
+  end
+
+  class Field
+    attr_reader :name
+
+    def initialize(name, options = {})
+      @name, @options = name, options
+    end
+
+    def validate(value, &error)
+      error.call(self, 'is required') if required? && value !~ /\S/
+
+      error.call(self, 'has too many lines') if !multiline? && value.lines.count > 1
+
+      error.call(self, 'has too many characters') if value.chars.count > char_limit
+
+      error.call(self, 'has too many words') if word_limit? && value.scan(/\w+/).length > word_limit
+
+      error.call(self, 'is invalid') if pattern? && value !~ pattern
+
+      error.call(self, 'is invalid') if values? && !values.include?(value)
+    end
+
+    def key
+      @key ||= @name.to_s
+    end
+
+    def key_required?
+      @options.fetch(:key_required) { true }
+    end
+
+    def label
+      @label ||= @options.fetch(:label) { Label.new(name) }
+    end
+
+    def required?
+      @options.fetch(:required) { true }
+    end
+
+    def multiline?
+      @options.fetch(:multiline) { false }
+    end
+
+    def multiple?
+      @options.fetch(:multiple) { false }
+    end
+
+    def char_limit
+      @options.fetch(:char_limit) { 64 }
+    end
+
+    def word_limit?
+      @options.has_key?(:word_limit)
+    end
+
+    def word_limit
+      @options.fetch(:word_limit)
+    end
+
+    def pattern?
+      @options.has_key?(:pattern)
+    end
+
+    def pattern
+      @options.fetch(:pattern)
+    end
+
+    def values?
+      @options.has_key?(:values)
+    end
+
+    def values
+      @options.fetch(:values)
+    end
+  end
+
+  module ArrayAttrAccessor
+    def array_attr_reader(name)
+      define_method(name) do
+        ivar = :"@#{name}"
+
+        values = instance_variable_get(ivar)
+
+        if values.nil?
+          values = []
+
+          instance_variable_set(ivar, values)
+        end
+
+        values
+      end
+    end
+
+    def array_attr_writer(name)
+      define_method(:"#{name}=") do |value|
+        ivar = :"@#{name}"
+
+        values = instance_variable_get(ivar)
+
+        if values.nil?
+          instance_variable_set(ivar, [value])
+        else
+          values << value
+        end
+      end
+    end
+
+    def array_attr_accessor(name)
+      array_attr_reader(name)
+      array_attr_writer(name)
+    end
+  end
+
+  module ClassMethods
+    include ArrayAttrAccessor
+
+    def fields
+      @fields ||= []
+    end
+
+    def field(*args)
+      field = Field.new(*args)
+
+      fields << field
+
+      if field.multiple?
+        array_attr_accessor field.name
+      else
+        attr_accessor field.name
+      end
+    end
+
+    def guard(&block)
+      fields << block
+    end
+
+    def checks
+      @checks ||= []
+    end
+
+    def check(&block)
+      checks << block
+    end
+
+    def errors
+      @errors ||= []
+    end
+
+    def error(message)
+      errors << message
+    end
+  end
+
+  class KeyError < StandardError; end
+
+  class ValueError < StandardError; end
+
+  class UserError < StandardError; end
+
+  module InstanceMethods
+    def parse(encoded_form_data)
+      form_data = CGI.parse(encoded_form_data)
+
+      self.class.fields.each do |field|
+        unless field.respond_to?(:key)
+          instance_eval(&field) ? return : next
+        end
+
+        unless form_data.has_key?(field.key)
+          next if field.multiple? || !field.key_required?
+
+          raise KeyError
+        end
+
+        values = form_data.delete(field.key)
+
+        if values.length > 1
+          raise ValueError unless field.multiple?
+        end
+
+        values.each do |value|
+          field.validate(value) do |error|
+            errors << UserError.new("#{field.label} #{error}")
+          end
+
+          send(:"#{field.name}=", value)
+        end
+      end
+
+      raise KeyError unless form_data.empty?
+
+      self.class.checks.zip(self.class.errors) do |check, error|
+        instance_eval(&check) ? next : errors << UserError.new(error)
+      end
+    end
+
+    def errors
+      @errors ||= []
+    end
+
+    def valid?
+      errors.empty?
+    end
+  end
+
+  def self.setup(form)
+    form.send :include, InstanceMethods
+
+    form.extend ClassMethods
+
+    if on_rails?
+      form.field(:utf8, key_required: false)
+
+      form.field(:authenticity_token, key_required: false)
+    end
+  end
+
+  def self.on_rails?
+    defined?(Rails)
+  end
+end

data/spec/formeze_spec.rb

@@ -0,0 +1,399 @@
+require 'minitest/autorun'
+
+require 'formeze'
+
+class FormWithField
+  Formeze.setup(self)
+
+  field :title
+end
+
+describe 'FormWithField' do
+  before do
+    @form = FormWithField.new
+  end
+
+  describe 'title method' do
+    it 'should return nil' do
+      @form.title.must_be_nil
+    end
+  end
+
+  describe 'title equals method' do
+    it 'should set the value of the title attribute' do
+      @form.title = 'Untitled'
+      @form.title.must_equal('Untitled')
+    end
+  end
+
+  describe 'parse method' do
+    it 'should set the value of the title attribute' do
+      @form.parse('title=Untitled')
+      @form.title.must_equal('Untitled')
+    end
+
+    it 'should raise an exception when the key is missing' do
+      proc { @form.parse('') }.must_raise(Formeze::KeyError)
+    end
+
+    it 'should raise an exception when there are multiple values for the key' do
+      proc { @form.parse('title=foo&title=bar') }.must_raise(Formeze::ValueError)
+    end
+
+    it 'should raise an exception when there is an unexpected key' do
+      proc { @form.parse('title=Untitled&foo=bar') }.must_raise(Formeze::KeyError)
+    end
+  end
+end
+
+describe 'FormWithField after parsing valid input' do
+  before do
+    @form = FormWithField.new
+    @form.parse('title=Untitled')
+  end
+
+  describe 'valid query method' do
+    it 'should return true' do
+      @form.valid?.must_equal(true)
+    end
+  end
+
+  describe 'errors method' do
+    it 'should return an empty array' do
+      @form.errors.must_be_instance_of(Array)
+      @form.errors.must_be_empty
+    end
+  end
+end
+
+describe 'FormWithField after parsing blank input' do
+  before do
+    @form = FormWithField.new
+    @form.parse('title=')
+  end
+
+  describe 'valid query method' do
+    it 'should return false' do
+      @form.valid?.must_equal(false)
+    end
+  end
+end
+
+describe 'FormWithField after parsing input containing newlines' do
+  before do
+    @form = FormWithField.new
+    @form.parse('title=This+is+a+product.%0AIt+is+very+lovely.')
+  end
+
+  describe 'valid query method' do
+    it 'should return false' do
+      @form.valid?.must_equal(false)
+    end
+  end
+end
+
+class FormWithOptionalField
+  Formeze.setup(self)
+
+  field :title, required: false
+end
+
+describe 'FormWithOptionalField after parsing blank input' do
+  before do
+    @form = FormWithOptionalField.new
+    @form.parse('title=')
+  end
+
+  describe 'valid query method' do
+    it 'should return true' do
+      @form.valid?.must_equal(true)
+    end
+  end
+end
+
+class FormWithFieldThatCanHaveMultipleLines
+  Formeze.setup(self)
+
+  field :description, multiline: true
+end
+
+describe 'FormWithFieldThatCanHaveMultipleLines after parsing input containing newlines' do
+  before do
+    @form = FormWithFieldThatCanHaveMultipleLines.new
+    @form.parse('description=This+is+a+product.%0AIt+is+very+lovely.')
+  end
+
+  describe 'valid query method' do
+    it 'should return true' do
+      @form.valid?.must_equal(true)
+    end
+  end
+end
+
+class FormWithCharacterLimitedField
+  Formeze.setup(self)
+
+  field :title, char_limit: 16
+end
+
+describe 'FormWithCharacterLimitedField after parsing input with too many characters' do
+  before do
+    @form = FormWithCharacterLimitedField.new
+    @form.parse('title=This+Title+Will+Be+Too+Long')
+  end
+
+  describe 'valid query method' do
+    it 'should return false' do
+      @form.valid?.must_equal(false)
+    end
+  end
+end
+
+class FormWithWordLimitedField
+  Formeze.setup(self)
+
+  field :title, word_limit: 2
+end
+
+describe 'FormWithWordLimitedField after parsing input with too many words' do
+  before do
+    @form = FormWithWordLimitedField.new
+    @form.parse('title=This+Title+Will+Be+Too+Long')
+  end
+
+  describe 'valid query method' do
+    it 'should return false' do
+      @form.valid?.must_equal(false)
+    end
+  end
+end
+
+class FormWithFieldThatMustMatchPattern
+  Formeze.setup(self)
+
+  field :number, pattern: /\A\d+\z/
+end
+
+describe 'FormWithFieldThatMustMatchPattern after parsing input that matches the pattern' do
+  before do
+    @form = FormWithFieldThatMustMatchPattern.new
+    @form.parse('number=12345')
+  end
+
+  describe 'valid query method' do
+    it 'should return true' do
+      @form.valid?.must_equal(true)
+    end
+  end
+end
+
+describe 'FormWithFieldThatMustMatchPattern after parsing input that does not match the pattern' do
+  before do
+    @form = FormWithFieldThatMustMatchPattern.new
+    @form.parse('number=notanumber')
+  end
+
+  describe 'valid query method' do
+    it 'should return false' do
+      @form.valid?.must_equal(false)
+    end
+  end
+end
+
+class FormWithFieldThatCanHaveMultipleValues
+  Formeze.setup(self)
+
+  field :colour, multiple: true
+end
+
+describe 'FormWithFieldThatCanHaveMultipleValues' do
+  before do
+    @form = FormWithFieldThatCanHaveMultipleValues.new
+  end
+
+  describe 'colour method' do
+    it 'should return an empty array' do
+      @form.colour.must_be_instance_of(Array)
+      @form.colour.must_be_empty
+    end
+  end
+
+  describe 'colour equals method' do
+    it 'should add the argument to the colour attribute array' do
+      @form.colour = 'black'
+      @form.colour.must_include('black')
+    end
+  end
+
+  describe 'parse method' do
+    it 'should add the value to the colour attribute array' do
+      @form.parse('colour=black')
+      @form.colour.must_include('black')
+    end
+
+    it 'should not raise an exception when there are multiple values for the key' do
+      @form.parse('colour=black&colour=white')
+    end
+
+    it 'should not raise an exception when the key is missing' do
+      @form.parse('')
+    end
+  end
+end
+
+describe 'FormWithFieldThatCanHaveMultipleValues after parsing input with multiple values' do
+  before do
+    @form = FormWithFieldThatCanHaveMultipleValues.new
+    @form.parse('colour=black&colour=white')
+  end
+
+  describe 'colour method' do
+    it 'should return an array containing the values' do
+      @form.colour.must_be_instance_of(Array)
+      @form.colour.must_include('black')
+      @form.colour.must_include('white')
+    end
+  end
+
+  describe 'valid query method' do
+    it 'should return true' do
+      @form.valid?.must_equal(true)
+    end
+  end
+end
+
+describe 'FormWithFieldThatCanHaveMultipleValues after parsing input with no values' do
+  before do
+    @form = FormWithFieldThatCanHaveMultipleValues.new
+    @form.parse('')
+  end
+
+  describe 'colour method' do
+    it 'should return an empty array' do
+      @form.colour.must_be_instance_of(Array)
+      @form.colour.must_be_empty
+    end
+  end
+
+  describe 'valid query method' do
+    it 'should return true' do
+      @form.valid?.must_equal(true)
+    end
+  end
+end
+
+class FormWithFieldThatCanOnlyHaveSpecifiedValues
+  Formeze.setup(self)
+
+  field :answer, values: %w(yes no)
+end
+
+describe 'FormWithFieldThatCanOnlyHaveSpecifiedValues after parsing input with an invalid value' do
+  before do
+    @form = FormWithFieldThatCanOnlyHaveSpecifiedValues.new
+    @form.parse('answer=maybe')
+  end
+
+  describe 'valid query method' do
+    it 'should return false' do
+      @form.valid?.must_equal(false)
+    end
+  end
+end
+
+class FormWithGuard
+  Formeze.setup(self)
+
+  field :delivery_address
+
+  field :same_address, values: %w(yes no)
+
+  guard { same_address? }
+
+  field :billing_address
+
+  def same_address?
+    same_address == 'yes'
+  end
+end
+
+describe 'FormWithGuard after parsing input with same_address set and no billing address' do
+  before do
+    @form = FormWithGuard.new
+    @form.parse('delivery_address=123+Main+St&same_address=yes')
+  end
+
+  describe 'valid query method' do
+    it 'should return true' do
+      @form.valid?.must_equal(true)
+    end
+  end
+end
+
+class FormWithCustomValidation
+  Formeze.setup(self)
+
+  field :email
+
+  check { email.include?(?@) }
+  error 'Email is invalid'
+end
+
+describe 'FormWithCustomValidation after parsing invalid input' do
+  before do
+    @form = FormWithCustomValidation.new
+    @form.parse('email=alice')
+  end
+
+  describe 'valid query method' do
+    it 'should return false' do
+      @form.valid?.must_equal(false)
+    end
+  end
+end
+
+class FormWithOptionalKey
+  Formeze.setup(self)
+
+  field :accept_terms, values: %w(true), key_required: false
+end
+
+describe 'FormWithOptionalKey after parsing input without the key' do
+  before do
+    @form = FormWithOptionalKey.new
+    @form.parse('')
+  end
+
+  describe 'valid query method' do
+    it 'should return true' do
+      @form.valid?.must_equal(true)
+    end
+  end
+end
+
+Rails = Object.new
+
+class RailsForm
+  Formeze.setup(self)
+
+  field :title
+end
+
+describe 'RailsForm' do
+  before do
+    @form = RailsForm.new
+  end
+
+  describe 'parse method' do
+    it 'should automatically process the utf8 and authenticity_token parameters' do
+      @form.parse('utf8=%E2%9C%93&authenticity_token=5RMc3sPZdR%2BZz4onNS8NfK&title=Test')
+      @form.authenticity_token.wont_be_empty
+      @form.utf8.wont_be_empty
+    end
+
+    it 'should not complain if the utf8 or authenticity_token parameters are missing' do
+      @form.parse('utf8=%E2%9C%93&title=Test')
+      @form.parse('authenticity_token=5RMc3sPZdR%2BZz4onNS8NfK&title=Test')
+    end
+  end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: formeze
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Tim Craft
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-09 00:00:00.000000000Z
+dependencies: []
+description: A little library for defining classes to handle form data/input
+email:
+- mail@timcraft.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/formeze.rb
+- spec/formeze_spec.rb
+- README.md
+- Rakefile.rb
+- formeze.gemspec
+homepage: http://github.com/timcraft/formeze
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: See description
+test_files: []