foraneus 0.0.5 → 0.0.6

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    ZGY5N2JmNGZjYjhlNjUyY2ZmMjRkOGQ0NGMwYjMxYTk2Y2UwNmYzNg==
+    MTdlYTI4OGY2Y2M4N2I3ODAxOTUyOThjYjYyYzA1MDlkNWMyZDliNg==
   data.tar.gz: !binary |-
-    YTRkOGRlZGQxZmM0YjQ2YTYwNWE0ZDI0NjkyYjQwMWNkZjlhZTE4NQ==
+    OWM3NWRlYzIyZGEzMzYyNDVmMGEzMWZiYWIzMzY2YmI4NWY0MjhmMQ==
 SHA512:
   metadata.gz: !binary |-
-    YTA3YzQwOTExOWE0ZGRjMjM3YTdlYzUwNjZlMTg1ZTNjNmM0NzllMTA5Mjdm
-    NjU5Y2U2YTYxZWViNTMyNTdlNDMyY2FjMDRkMDIzMzFlNmYzZjA1MDBmYTNi
-    YTFiYzkwMDdiZmY4MTVlNzZlODAwOTg1NDcyMmU1ZDUwNzJmYjM=
+    MmQyNTdlNmFmNjNiNGM4MWIxYjcyMmExNWIxNDQxODA0MTdkNzFiMGFhMTVk
+    M2E3ZWVhNzRmM2Q5ZDBkOGU3OTEzZDVjMzU1YTk3NGRhZTEyYWRkNDU3Yzc3
+    Njc2N2Y0Mjk5NWYzNTBmM2UwNWUxNjgxMTVhMjk0YzNjNWZiZWU=
   data.tar.gz: !binary |-
-    MjQxNDExM2Y5OTJiZDk5MGUyNjE1NTI4OWM5ZTllZDYxYTRhMzk1ODNkOGMy
-    YzMyNTEzMjk0OGI3NDYyMjU0NjNkM2Y2MTBhZTk1ZGM5ODZlN2VhMzExNDQz
-    YzFkNTE2MzRhZGM0Zjk2ODU4OTkzMmZjZGFiOWNjZTE3MmMxMDg=
+    YmUyYjQyZDNjZWI1NzllOTNhZTVkZjZmMjBiZDkyMjFhOTQ5OGE1MmU4NTYx
+    MTYzYjMwMWY4OTAwY2YzODQzNzg1YTJhMDE2MTYxNmFmYTQ1ZjYxNzBlZGM3
+    ZjU3ZjMzMGJjNWQ2Y2IwNTY1YmJkZDU5ZGU4N2NlYjBhNzFhMmE=

data/README.md

@@ -1,8 +1,17 @@
 # Foraneus
 
-## Usage
+Foraneus allows to:
+ - parse data coming from external sources (like an HTTP request).
+ - convert data back to a raw representation suitable for being used at the outside, like an HTML
+form.
+
+No matter which source of data is fed into Foraneus (external or internal), any instance can return
+raw and parsed data.
+
+## Basic usage
 
  - Declaration:
+
   ``` ruby
   class MyForm < Foraneus
     integer :delay
@@ -26,12 +35,23 @@
   form[]      # => { :delay => '5', :duration => '2.14' }
   ```
 
+ - From the inside:
+
   ``` ruby
-  form.valid?   # => true
-  form.errors   # => {}
+  form = MyForm.raw(:delay => 5, :duration => 2.14)
   ```
 
- - From the inside:
+  ``` ruby
+  form.delay    # => 5
+  form[:delay]  # => '5'
+  ```
+
+  ``` ruby
+  form.data   # => { :delay => 5, :duration => 2.14 }
+  form[]      # => { :delay => '5', :duration => '2.14' }
+  ```
+
+ - When no data:
 
   ``` ruby
   form = MyForm.new
@@ -42,22 +62,85 @@
   form[:delay]  # => nil
   ```
 
- - From the inside:
+## Declaration
+
+Declare source classes by inheriting from `Foraneus` base class.
 
   ``` ruby
-  form = MyForm.raw(:delay => 5, :duration => 2.14)
+  class MyForm < Foraneus
+    field :delay, SomeCustomConverter.new
+    float :duration
+  end
   ```
 
+Fields are declared in two ways:
+
+ - calling `.field`
+ - calling a shortcut method, like `.float`
+
+
+There are handy methods for any of the built-in converters: boolean, date, decimal, float, integer,
+noop, and string.
+
+When no converter is passed to `.field`, Foraneus::Converters::Noop is assigned to the declared
+field.
+
+## Converters
+
+Converters have two interrelated responsibilities:
+
+ - Parse data, like the string `"3,000"`, into an object, `like 3_000`.
+ - Serialize data, like integer `3_000`, into string `"3,000"`
+
+A converter is simply an object that responds to `#parse(s)` and `#raw(v)` methods.
+
+When `#parse(s)` raises a StandardError exception, or any of its descendants, the exception is
+rescued and a Foraneus::Error instance is added to `Foraneus#errors` map.
+
+Built-in converters:
+
+ - Boolean
+ - Date
+ - Decimal
+ - Float
+ - Integer
+ - Noop
+ - String
+
+## Validations
+
+Foraneus only validates that external data can be converted to the specified types. Smart
+validations, like date range inclusion, are out of the scope of this gem.
+
+`#valid?` and `#errors` are handy methods that tell whether a Foraneus instance is valid or not.
+
+Valid instance:
+
   ``` ruby
-  form.delay    # => 5
-  form[:delay]  # => '5'
+  form.valid?     # => true
+  form[:errors]   # => {}
   ```
 
+Invalid one:
   ``` ruby
-  form.data   # => { :delay => 5, :duration => 2.14 }
-  form[]      # => { :delay => '5', :duration => '2.14' }
+  form = MyForm.parse(:delay => 'INVALID')
+
+  form.valid?                     # => false
+
+  form[:errors][:delay].key       # => 'ArgumentError'
+  form[:errors][:delay].message   # => 'invalid value for Integer(): "INVALID"'
   ```
 
+`#errors` is a map in which keys correspond to field names, and values are instances of
+`Foraneus::Error`.
+
+The name of the exception raised by `#parse` is to the error's `key` attribute, and the exception's
+message is added to the error's `message` attribute.
+
+
+Data coming from the inside is assumed to be valid, so `.raw` won't return an instance having
+errors neither being invalid.
+
 ## Installation
 
  - Install `foraneus` as a gem.

data/lib/foraneus.rb

@@ -15,11 +15,13 @@ class Foraneus
 
   attr_accessor :data
 
-  def initialize
+  def initialize(data = {})
     @data = {}
     @raw_data = {}
 
     @errors = {}
+
+    self.class.send(:__raw, self, data)
   end
 
   def self.boolean(name)
@@ -107,6 +109,10 @@ class Foraneus
   def self.raw(data)
     instance = self.new
 
+    __raw(instance, data)
+  end
+
+  def self.__raw(instance, data)
     data.each do |k, v|
       next unless fields.has_key?(k.to_s)
       instance.send("#{k}=", v)
@@ -124,6 +130,7 @@ class Foraneus
 
     instance
   end
+  private_class_method :__raw
 
   def [](m = nil)
     if m == :errors

data/spec/lib/foraneus/converters/decimal_converter_spec.rb

@@ -6,7 +6,7 @@ describe Foraneus::Converters::Decimal do
 
   describe '#parse' do
     it 'parses a decimal representation' do
-      s = '1,234.56'
+      s = '1234.56'
       n = BigDecimal.new('1234.56')
 
       converter.parse(s).should eq(n)

data/spec/lib/foraneus/converters/float_converter_spec.rb

@@ -4,7 +4,7 @@ describe Foraneus::Converters::Float do
 
   describe '#parse' do
     context 'with valid values' do
-      let(:number) { 2.3412 }
+      let(:number) { 1234.5678 }
       let(:raw_number) { number.to_s }
 
       it 'returns a float number' do

data/spec/lib/foraneus/converters/integer_converter_spec.rb

@@ -4,7 +4,7 @@ describe Foraneus::Converters::Integer do
 
   describe '#parse' do
     context 'with valid values' do
-      let(:number) { 2 }
+      let(:number) { 1234 }
       let(:raw_number) { number.to_s }
 
       it 'returns an integer number' do

data/spec/lib/foraneus_spec.rb

@@ -20,6 +20,16 @@ describe Foraneus do
     its(:data) { should be_empty }
 
     its([]) { should be_empty }
+
+    context 'when initial data' do
+      subject(:form) { form_spec.new(:delay => 5) }
+
+      its(:delay)     { should eq(5) }
+      its([:delay])   { should eq('5') }
+
+      its(:data)    { should include(:delay => 5) }
+      its([])  { should include(:delay => '5') }
+    end
   end
 
   describe '.parse' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: foraneus
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - Gianfranco Zas
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-12 00:00:00.000000000 Z
+date: 2014-05-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -24,7 +24,7 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: Provides validation and transformation mechanisms to external data.
+description: Provides two way transformation mechanisms to external data.
 email: snmgian@gmail.com
 executables: []
 extensions: []
@@ -74,7 +74,7 @@ rubyforge_project:
 rubygems_version: 2.1.5
 signing_key: 
 specification_version: 4
-summary: Validates and transform external data.
+summary: Transforms external data.
 test_files:
 - spec/lib/foraneus_spec.rb
 - spec/lib/foraneus/converters/noop_converter_spec.rb