foraneus 0.0.15 → 0.0.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d581bebcc546182ffb84546ff4fb8ad667ee126f
-  data.tar.gz: 241b1dfc78a1837a6ec6404904ab1a4b1f6d3125
+  metadata.gz: 026d8cac77a7a732c918a057f4eac4b965a92180
+  data.tar.gz: 2fd7da19d82c382269c1cfd1425defbfe97a5253
 SHA512:
-  metadata.gz: 457b8493632fb86f01ea610b164f05df68c0f85f156ab26d3c7fe98ee62a2262c9a2281dd037f636ffb31fac42b49f68ad66386dcd264db5023134d9ef0fbe15
-  data.tar.gz: 4c668906d942e090e563b7ec8a8241c4cfa1cb42096bad58146c168aca89672cdd82b1a92c99896fd8bcf7af7c354d5a9e525fb7a32122f9900103fc4060d52d
+  metadata.gz: 8a97fdb7d2fcc3940fb788f7783c4525dc4b32305a732c2d736a0a2fb436e81460020a23faadcf4346f4284b1dfd54722edc964dbbf18fd6b2517fdcbd0755b6
+  data.tar.gz: f76ff7fe5ca5b27971cfa1cdad7b725303d4428d44ee5a737cdbc3699522e2f6c508f1e5282c47344941a483377bb2cbb6b3c941bc05da5ddb15c92eb1ce8bc6

data/README.md

@@ -47,7 +47,10 @@ raw and parsed data.
   ```
 
   ``` ruby
+  # the parsed attributes
   form.data   # => { :delay => 5, :duration => 2.14 }
+
+  # the received attributes
   form[]      # => { :delay => '5', :duration => '2.14' }
   ```
 
@@ -163,6 +166,24 @@ If an external value is not fed into a required field, an error with key `KeyErr
   form.errors[:delay].message     # => 'required parameter not found: "delay"'
   ```
 
+## Absence of optional fields
+
+Absent fields are treated as `nil` when invoking accessor methods.
+
+  ``` ruby
+  MyForm = Class.new(Foraneus) { string :name }
+  form = MyForm.parse
+
+  form.name       # => nil
+  ```
+
+Data accessors don't include any absent field.
+
+  ``` ruby
+  form.data       # => {}
+  form[]          # => {}
+  ```
+
 ## Blank values
 
 By default, any blank value is treated as nil.
@@ -197,8 +218,12 @@ Parse data from the ouside:
   form = MyForm.parse
 
   form.name             # => 'Alice'
+  form.data             # => { :name => 'Alice' }
+
   form[:name]           # => nil, because data from the outside
                         #    don't include any value
+
+  form[]                # => {}
   ```
 
 Convert values back from the inside:
@@ -235,6 +260,165 @@ It is possible to rename methods `#errors` and `#data` so it will not conflict w
   form.non_clashing_data      # { :errors => 'some errors', :data => 'some data' }
   ```
 
+## Nesting
+Forms can also have form fields.
+
+  ``` ruby
+  class Profile < Foraneus
+    string  :email
+
+    form    :coords do
+      integer :x
+      integer :y
+    end
+  end
+  ```
+
+  ``` ruby
+  profile = Profile.parse(:email => 'mail@example.org', :coords => { :x => '1', :y => '2' })
+
+  profile.email     # => mail@example.org
+
+  profile.coords.x # => 1
+  profile.coords.y # => 2
+
+  profile.coords[:x] # => '1'
+  profile.coords[:y] # => '2'
+
+  ```
+
+  ``` ruby
+  profile.coords.data # => { :x => 1, :y => 2 }
+  profile.coords[]    # => { :x => '1', :y => '2' }
+  ```
+
+  ``` ruby
+  profile[:coords] # =>  { :x => '1', :y => '2' }
+  ```
+
+  ``` ruby
+  profile.data # => { :email => 'mail.example.org', :coords => { :x => 1, :y => 2 } }
+  profile[] # => { :email => 'mail@example.org', :coords => { :x => '1', :y => '2' } }
+  ```
+
+ - Absence
+  ``` ruby
+  profile = Profile.parse
+
+  profile.coords # => nil
+  profile.data   # => {}
+  profile[]      # => {}
+  ```
+
+  - .Nullity
+  ``` ruby
+  profile = Profile.parse(:coords => nil)
+
+  profile.coords # => nil
+  profile.data   # => { :coords => nil }
+  profile[]      # => { :coords => nil }
+  ```
+
+ - Emptiness
+  ``` ruby
+  profile = Profile.parse(:coords => {})
+
+  profile.coords.x    # => nil
+  profile.coords.y    # => nil
+
+  profile.coords.data # => {}
+  profile.coords[]    # => {}
+
+  profile.data  # => { :coords => {} }
+  profile[] # => { :coords => {} }
+  ```
+
+ - Validations
+  ``` ruby
+  profile = Profile.parse(:coords => { :x => '0', :y => '0' })
+
+  profile.coords.valid? # => true
+  profile.coords.errors # => {}
+  ```
+
+  ``` ruby
+  profile = Profile.parse(:coords => { :x => 'FIVE' })
+
+  profile.coords.x  # => nil
+
+  profile.coords.valid? # => false
+
+  profile.coords.errors[:x].key # => 'ArgumentError'
+  profile.coords.errors[:x].message   # => 'invalid value for Integer(): "FIVE"'
+
+  profile.valid?  # => false
+
+  profile.errors[:coords].key # => 'NestedFormError'
+  profile.errors[:coords].message # => 'Invalid nested form: coords'
+  ```
+
+  ``` ruby
+  profile = Profile.parse(:coords => 'FIVE,SIX')
+
+  profile.coords    # => nil
+
+
+  profile.valid?  # => false
+  profile.errors[:coords].key # => 'NestedFormError'
+  profile.errors[:coords].message # => 'Invalid nested form: coords'
+  ```
+
+ - From the inside:
+  ``` ruby
+  profile = Profile.raw(:email => 'mail@example.org', :coords => { :x => 1, :y => 2 })
+  ```
+
+  ``` ruby
+  profile.coords.x  # => 1
+  profile.coords.data  # => { :x => 1, :y => 2 }
+
+  profile.coords[:x] # => '1'
+  profile.coords[]  # => { :x => '1', :y => '2' }
+  ```
+
+  ``` ruby
+  profile.data # => { :email => 'email.example.org', :coords => { :x => 0, :y => 0 } }
+  profile[] # => { :email => 'email@example.org', :coords => { :x => '0', :y => '0' } }
+  ```
+  - .Absence
+
+  ```
+  profile = Profile.raw
+
+  profile.coords # => nil
+  profile.data   # => {}
+  profile[]      # => {}
+  ```
+
+  - .Nullity
+  ``` ruby
+  profile = Profile.raw(:coords => nil)
+
+  profile.coords # => nil
+  profile.data   # => { :coords => nil }
+  profile[]      # => { :coords => nil }
+  ```
+
+  - .Emptiness
+  ``` ruby
+  profile = Profile.raw(:coords => {})
+
+  profile.coords.x  # => nil
+  profile.coords.y  # => nil
+
+  profile.coords.data # => {}
+  profile.coords[]    # => {}
+
+  profile.data      # => { :coords => {} }
+  profile[]      # => { :coords => {} }
+  ```
+
+
 ## Installation
 
  - Install `foraneus` as a gem.

data/lib/foraneus.rb

@@ -1,3 +1,7 @@
+# TODO refactor
+class NestedFormError < StandardError
+end
+
 if RUBY_VERSION == '1.8.7'
   require 'foraneus/compatibility/ruby-1.8.7'
 end
@@ -7,6 +11,7 @@ require 'foraneus/converters/date'
 require 'foraneus/converters/decimal'
 require 'foraneus/converters/float'
 require 'foraneus/converters/integer'
+require 'foraneus/converters/nested'
 require 'foraneus/converters/noop'
 require 'foraneus/converters/string'
 require 'foraneus/errors'
@@ -55,6 +60,15 @@ class Foraneus
     field(name, converter)
   end
 
+  # Declares a nested form field
+  #
+  # @param [Symbol] name The name of the field.
+  # @yield Yields to a nested foraneus spec.
+  def self.form(name, &block)
+    converter = Class.new(Foraneus::Converters::Nested, &block)
+    field(name, converter)
+  end
+
   # Declares an integer field.
   #
   # @param [Symbol] name The name of the field.
@@ -180,9 +194,6 @@ class Foraneus
   # @param [Symbol] k Field name.
   # @param [String] v Raw value.
   def []=(k, v)
-    #raw_data = @_
-
-    #raw_data[k] = v
     @_[k] = v
   end
 
@@ -196,12 +207,25 @@ class Foraneus
 
     v, error = Utils.parse_datum(field, s, converter)
 
-    unless error
+    if error.nil? && !v.nil? && Foraneus::Utils.nested_converter?(converter)
+      instance.send(self.accessors[:data])[field.to_sym] = v.data if is_present
+      instance.send("#{field}=", v)
+      unless v.valid?
+        error = Foraneus::Error.new('NestedFormError', "Invalid nested form: #{field}")
+        instance.send(self.accessors[:errors])[field.to_sym] = error
+      end
+
+    elsif error.nil?
       instance.send("#{field}=", v)
       instance.send(self.accessors[:data])[field.to_sym] = v if is_present || converter.opts.include?(:default)
+    else
+      if Foraneus::Utils.nested_converter?(converter)
+        error = Foraneus::Error.new('NestedFormError', "Invalid nested form: #{field}")
+        instance.send(self.accessors[:errors])[field.to_sym] = error
+      else
+        instance.send(self.accessors[:errors])[field.to_sym] = error if error
+      end
     end
-
-    instance.send(self.accessors[:errors])[field.to_sym] = error if error
   end
   private_class_method :__parse_field
 
@@ -216,7 +240,17 @@ class Foraneus
 
     s = Utils.raw_datum(v, converter)
 
-    instance[field.to_sym] = s if is_present || converter.opts.include?(:default)
+    if Foraneus::Utils.nested_converter?(converter)
+      instance.send("#{field}=", s)
+    end
+
+    if is_present || converter.opts.include?(:default)
+      if Foraneus::Utils.nested_converter?(converter) && !s.nil?
+        instance[field.to_sym] = s[]
+      else
+        instance[field.to_sym] = s
+      end
+    end
   end
   private_class_method :__raw_field
 

data/lib/foraneus/converters/nested.rb

@@ -0,0 +1,9 @@
+class Foraneus
+  module Converters
+    class Nested < Foraneus
+
+      def self.opts; {}; end
+
+    end
+  end
+end

data/lib/foraneus/utils.rb

@@ -67,6 +67,10 @@ class Foraneus
       converter.raw(v) unless v.nil?
     end
 
+    def self.nested_converter?(converter)
+      Class === converter && converter.ancestors.include?(Foraneus)
+    end
+
     # Creates a singleton attribute accessor on an instance.
     #
     # @param [Foraneus] instance

data/spec/lib/foraneus_nesting_spec.rb

@@ -0,0 +1,231 @@
+require 'spec_helper'
+
+describe Foraneus do
+
+  let(:converter) { Foraneus::Converters::Integer.new }
+
+  let(:form_spec) {
+    c = converter
+    Class.new(Foraneus) do
+      string :email
+
+      form :coords do
+        field :x, c
+        integer :y
+      end
+    end
+  }
+
+  describe '.parse' do
+    describe 'with parseable data' do
+      subject { form_spec.parse(:email => 'mail@example.org', :coords => { :x => '1', :y => '2' }) }
+
+      it 'parses the nested form' do
+        assert_equal 'mail@example.org', subject.email
+
+        assert_equal 1, subject.coords.x
+        assert_equal 2, subject.coords.y
+
+        assert_equal '1', subject.coords[:x]
+        assert_equal '2', subject.coords[:y]
+
+        assert_equal({ :x => 1, :y => 2 }, subject.coords.data)
+
+        assert_equal({ :x => '1', :y => '2' }, subject.coords[])
+
+        assert subject.coords.valid?
+
+        assert_empty subject.coords.errors
+      end
+
+      it 'treats the field as a regular one from the point of view of the parent form' do
+        assert_equal({ :email => 'mail@example.org', :coords => { :x => 1, :y => 2 } }, subject.data)
+
+        assert_equal({ :x => '1', :y => '2' }, subject[:coords])
+        assert_equal({ :email => 'mail@example.org', :coords => { :x => '1', :y => '2' } }, subject[])
+
+        assert subject.valid?
+
+        assert_empty subject.errors
+      end
+    end
+
+    describe 'with absent data' do
+      subject { form_spec.parse }
+
+      it 'parses' do
+        assert_nil subject.coords
+
+        refute_includes subject.data, :coords
+        refute_includes subject[], :coords
+      end
+    end
+
+    describe 'with nil data' do
+      subject { form_spec.parse(:coords => nil) }
+
+      it 'parses' do
+        assert_nil subject.coords
+
+        assert_equal({ :coords => nil }, subject.data)
+        assert_equal({ :coords => nil }, subject[])
+      end
+    end
+
+    describe 'with empty data' do
+      subject { form_spec.parse(:coords => {}) }
+
+      it 'parses' do
+        assert_nil subject.coords.x
+        assert_nil subject.coords.y
+
+        assert_empty subject.coords.data
+        assert_empty subject.coords[]
+
+        assert_equal({ :coords => {} }, subject.data)
+        assert_equal({ :coords => {} }, subject[])
+      end
+    end
+
+
+    describe 'with unparseable nested data' do
+      subject { form_spec.parse(:coords => { :x => 'FIVE' }) }
+
+      it 'parses' do
+        assert_nil subject.coords.x
+
+        assert_equal 'FIVE', subject.coords[:x]
+        assert_equal({ :x => 'FIVE' }, subject.coords[])
+
+
+        refute subject.coords.valid?
+        assert_includes subject.coords.errors, :x
+      end
+
+      describe 'an error' do
+        let(:error) { subject.coords.errors.values.first }
+
+        let(:converter_exception) do
+          begin
+            converter.parse('FIVE')
+          rescue
+            e = $!
+          end
+
+          e
+        end
+
+        it 'provides a key' do
+          assert_equal converter_exception.class.name, error.key
+        end
+
+        it 'provides a message' do
+          assert_equal converter_exception.message, error.message
+        end
+      end
+
+      describe 'the parent form' do
+        it 'is marked as invalid with errors' do
+          refute subject.valid?
+
+          assert_includes subject.errors, :coords
+        end
+
+        describe 'the error' do
+          let(:error) { subject.errors[:coords] }
+
+          it 'provides a key' do
+            assert_equal 'NestedFormError', error.key
+          end
+
+          it 'provides a message' do
+            assert_equal 'Invalid nested form: coords', error.message
+          end
+        end
+      end
+    end
+
+    describe 'with non enclosing parseable data' do
+      subject { form_spec.parse(:coords => 'FIVE,SIX') }
+
+      it 'parses' do
+        assert_nil subject.coords
+
+        refute subject.valid?
+      end
+
+      describe 'the error' do
+        let(:error) { subject.errors[:coords] }
+
+        it 'provides a key' do
+          assert_equal 'NestedFormError', error.key
+        end
+
+        it 'provides a message' do
+          assert_equal 'Invalid nested form: coords', error.message
+        end
+      end
+    end
+  end
+
+  describe '.raw' do
+    subject { form_spec.raw(:email => 'mail@example.org', :coords => { :x => 1, :y => 2 }) }
+
+    it 'parses' do
+      assert_equal 1, subject.coords.x
+      assert_equal 2, subject.coords.y
+
+      assert_equal({ :x => 1, :y => 2 }, subject.coords.data)
+
+      assert_equal '1', subject.coords[:x]
+      assert_equal '2', subject.coords[:y]
+
+      assert_equal({ :x => '1', :y => '2' }, subject.coords[])
+    end
+
+    describe 'parent form' do
+      it 'parses' do
+        assert_equal({:email => 'mail@example.org', :coords => {:x => 1, :y => 2}}, subject.data)
+
+        assert_equal({ :email => 'mail@example.org', :coords => { :x => '1', :y => '2' } }, subject[])
+      end
+    end
+
+    describe 'with absent data' do
+      subject { form_spec.raw }
+
+      it 'parses' do
+        assert_nil subject.coords
+
+        assert_empty subject.data
+        assert_empty subject[]
+      end
+    end
+
+    describe 'with nil data' do
+      subject { form_spec.raw(:coords => nil) }
+
+      it 'parses' do
+        assert_nil subject.coords
+
+        assert_equal({ :coords => nil }, subject.data)
+        assert_equal({ :coords => nil }, subject[])
+      end
+    end
+
+    describe 'with empty data' do
+      subject { form_spec.raw(:coords => {}) }
+
+      it 'parses' do
+        assert_nil subject.coords.x
+        assert_nil subject.coords.y
+
+        assert_empty subject.coords.data
+        assert_empty subject.coords[]
+
+        assert_equal({ :coords => {} }, subject.data)
+        assert_equal({ :coords => {} }, subject[])
+      end
+    end
+  end
+end

data/spec/lib/foraneus_spec.rb

@@ -145,11 +145,11 @@ describe Foraneus do
           end
 
           it 'provides a key' do
-            assert_equal error.key, converter_exception.class.name
+            assert_equal converter_exception.class.name, error.key
           end
 
           it 'provides a message' do
-            assert_equal error.message, converter_exception.message
+            assert_equal converter_exception.message, error.message
           end
         end
       end

data/spec/spec_helper.rb

@@ -1,5 +1,3 @@
-#require 'rubygems'
-
 require 'minitest/autorun'
 require 'minitest/spec'
 require 'minitest/unit'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: foraneus
 version: !ruby/object:Gem::Version
-  version: 0.0.15
+  version: 0.0.16
 platform: ruby
 authors:
 - Gianfranco Zas
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-04-25 00:00:00.000000000 Z
+date: 2015-06-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -68,6 +68,7 @@ files:
 - lib/foraneus/converters/decimal.rb
 - lib/foraneus/converters/float.rb
 - lib/foraneus/converters/integer.rb
+- lib/foraneus/converters/nested.rb
 - lib/foraneus/converters/noop.rb
 - lib/foraneus/converters/string.rb
 - lib/foraneus/errors.rb
@@ -79,6 +80,7 @@ files:
 - spec/lib/foraneus/converters/integer_converter_spec.rb
 - spec/lib/foraneus/converters/noop_converter_spec.rb
 - spec/lib/foraneus/converters/string_converter_spec.rb
+- spec/lib/foraneus_nesting_spec.rb
 - spec/lib/foraneus_spec.rb
 - spec/runner.rb
 - spec/spec_helper.rb
@@ -114,6 +116,7 @@ test_files:
 - spec/lib/foraneus/converters/integer_converter_spec.rb
 - spec/lib/foraneus/converters/boolean_converter_spec.rb
 - spec/lib/foraneus/converters/string_converter_spec.rb
+- spec/lib/foraneus_nesting_spec.rb
 - spec/lib/foraneus_spec.rb
 - spec/runner.rb
 - spec/spec_helper.rb