foraneus 0.0.6 → 0.0.7

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MTdlYTI4OGY2Y2M4N2I3ODAxOTUyOThjYjYyYzA1MDlkNWMyZDliNg==
+    ZWMwYTU4OWRiZmI3YWMyYzVjYTc3OTc1YzJiOTUzZDM4YmU5YzZjNw==
   data.tar.gz: !binary |-
-    OWM3NWRlYzIyZGEzMzYyNDVmMGEzMWZiYWIzMzY2YmI4NWY0MjhmMQ==
+    Mjc1YzUwODZhMTRiZmFhNTcxZjljYTQ3YzY1Nzk3NDA3Y2YyOTkyZQ==
 SHA512:
   metadata.gz: !binary |-
-    MmQyNTdlNmFmNjNiNGM4MWIxYjcyMmExNWIxNDQxODA0MTdkNzFiMGFhMTVk
-    M2E3ZWVhNzRmM2Q5ZDBkOGU3OTEzZDVjMzU1YTk3NGRhZTEyYWRkNDU3Yzc3
-    Njc2N2Y0Mjk5NWYzNTBmM2UwNWUxNjgxMTVhMjk0YzNjNWZiZWU=
+    MjY2MmFlYmQ2MzhlMzBhOWM0MTE0ZWQ1N2ZmZDI4MmVhMzkxMzA5Nzg0NmY4
+    MzM1YjJmNzNiNzQ0YWU4MTY4ZDcxNTkzNjMzZTdjMjY5ZTdiNDY4ODJlYjdh
+    YWRhOWZmNTY0NTBmMDhiMTIyNjk4ZTU4M2ZmODI2NjMwM2ZhZDM=
   data.tar.gz: !binary |-
-    YmUyYjQyZDNjZWI1NzllOTNhZTVkZjZmMjBiZDkyMjFhOTQ5OGE1MmU4NTYx
-    MTYzYjMwMWY4OTAwY2YzODQzNzg1YTJhMDE2MTYxNmFmYTQ1ZjYxNzBlZGM3
-    ZjU3ZjMzMGJjNWQ2Y2IwNTY1YmJkZDU5ZGU4N2NlYjBhNzFhMmE=
+    ZmRmZGI3NjFiODYzOGU1NDNjMGUwMTQ1NTkxODUzNGYwZmYzNzQxZWY0ZTY2
+    NjA4NjZmMjQxYTY5ZGJkNzQwOWYyMGYxN2UxNmVhYzgzYzQ5MzI4ZTZlNTA3
+    YTZhNTUyYWUwZjAwODE4YzBiZThkM2M3NWI1NWNkODg4YjAxMzk=

data/README.md

@@ -51,17 +51,6 @@ raw and parsed data.
   form[]      # => { :delay => '5', :duration => '2.14' }
   ```
 
- - When no data:
-
-  ``` ruby
-  form = MyForm.new
-  ```
-
-  ``` ruby
-  form.delay    # => nil
-  form[:delay]  # => nil
-  ```
-
 ## Declaration
 
 Declare source classes by inheriting from `Foraneus` base class.
@@ -85,6 +74,16 @@ noop, and string.
 When no converter is passed to `.field`, Foraneus::Converters::Noop is assigned to the declared
 field.
 
+## Instantiation
+
+Foraneus instances can be obtained by calling two methods: `parse` and `raw`.
+
+Use `.parse` when:
+ - data is coming from outside of the system, like an HTTP request.
+
+Use `.raw` when:
+ - data is coming from the inside of the system, like a business layer.
+
 ## Converters
 
 Converters have two interrelated responsibilities:
@@ -122,6 +121,7 @@ Valid instance:
   ```
 
 Invalid one:
+
   ``` ruby
   form = MyForm.parse(:delay => 'INVALID')
 
@@ -134,10 +134,9 @@ Invalid one:
 `#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
+The name of the exception raised by `#parse` is 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.
 
@@ -157,6 +156,16 @@ Tests are written in RSpec. To run them all just execute the following from your
   rspec
   ```
 
+## Code documentation
+
+Documentation is written in Yard. To see it in a browser, execute this command:
+
+  ``` shell
+  yard server --reload
+  ```
+
+Then point the browser to `http://localhost:8808/`.
+
 ## Badges
 
 [![Build Status](https://travis-ci.org/snmgian/foraneus.svg?branch=master)](https://travis-ci.org/snmgian/foraneus) [![Code Climate](https://codeclimate.com/github/snmgian/foraneus.png)](https://codeclimate.com/github/snmgian/foraneus)

data/lib/foraneus/converters/boolean.rb

@@ -1,7 +1,14 @@
 class Foraneus
   module Converters
 
+    # Boolean converter.
+    #
+    # When parsing, the string 'true' is converted to true, otherwise false is returned.
+    #
+    # When converting to a raw value, a true value => 'true', a false value => 'false'.
     class Boolean
+
+      # @return [Boolean]
       def parse(s)
         if s == 'true'
           true

data/lib/foraneus/converters/date.rb

@@ -7,10 +7,13 @@ class Foraneus
 
       DEFAULT_FORMAT = '%Y-%m-%d'
 
+      # @param [Hash] opts
+      # @option opts [String] format Date format.
       def initialize(opts = {})
         @format = opts[:format] || DEFAULT_FORMAT
       end
 
+      # return [Date]
       def parse(s)
         ::Date.strptime(s, @format)
       end

data/lib/foraneus/converters/decimal.rb

@@ -4,21 +4,30 @@ class Foraneus
   module Converters
 
     class Decimal
-      DEFAULT_DELIMITER = ','
       DEFAULT_SEPARATOR = '.'
 
       DELIMITED_REGEX = /(\d)(?=(\d\d\d)+(?!\d))/
 
+      # @param [Hash] opts
+      # @option opts [String] delimiter Thousands delimiter.
+      # @option opts [String] separator Decimal separator.
+      # @option opts [Integer] precision Minimum precision.
       def initialize(opts = {})
-        @delimiter = opts[:delimiter] || DEFAULT_DELIMITER
-        @separator = opts[:separator] || DEFAULT_SEPARATOR
+        @delimiter = opts[:delimiter]
         @precision = opts[:precision]
+        @separator = opts[:separator] || DEFAULT_SEPARATOR
       end
 
+      # @return [BigDecimal]
       def parse(s)
         parts = s.split(@separator)
 
-        integer_part = (parts[0] || '0').gsub(@delimiter, '')
+        integer_part = (parts[0] || '0')
+
+        if @delimiter
+          integer_part.gsub!(@delimiter, '')
+        end
+
         fractional_part = parts[1] || '0'
 
         BigDecimal.new("#{integer_part}.#{fractional_part}")
@@ -31,7 +40,9 @@ class Foraneus
           right = add_trailing_zeros(right, @precision - right.length)
         end
 
-        left.gsub!(DELIMITED_REGEX) { "#{$1}#{@delimiter}" }
+        if @delimiter
+          left.gsub!(DELIMITED_REGEX) { "#{$1}#{@delimiter}" }
+        end
 
         "#{left}#{@separator}#{right}"
       end

data/lib/foraneus/converters/float.rb

@@ -7,12 +7,17 @@ class Foraneus
 
       DELIMITED_REGEX = /(\d)(?=(\d\d\d)+(?!\d))/
 
+      # @param [Hash] opts
+      # @option opts [String] delimiter Thousands delimiter.
+      # @option opts [String] separator Decimal separator.
+      # @option opts [Integer] precision Minimum precision.
       def initialize(opts = {})
         @delimiter = opts[:delimiter]
         @precision = opts[:precision]
         @separator = opts[:separator] || DEFAULT_SEPARATOR
       end
 
+      # @return [Float]
       def parse(s)
         if s == ''
           raise ArgumentError, 'invalid value for Float(): ""'

data/lib/foraneus/converters/integer.rb

@@ -4,10 +4,13 @@ class Foraneus
     class Integer
       DELIMITED_REGEX = /(\d)(?=(\d\d\d)+(?!\d))/
 
+      # @param [Hash] opts
+      # @option opts [String] delimiter Thousands delimiter.
       def initialize(opts = {})
         @delimiter = opts[:delimiter]
       end
 
+      # @return [Integer]
       def parse(s)
         s = s.gsub(@delimiter, '') if @delimiter
 

data/lib/foraneus/converters/noop.rb

@@ -1,7 +1,12 @@
 class Foraneus
   module Converters
 
+    # Noop converter.
+    #
+    # It does not perform any conversion at all. Useful when its needed to have a field but
+    # conversion is handled at another level.
     class Noop
+      # @return [Object]
       def parse(o)
         o
       end

data/lib/foraneus/converters/string.rb

@@ -2,6 +2,8 @@ class Foraneus
   module Converters
 
     class String
+
+      # @return [String]
       def parse(s)
         s.to_s
       end

data/lib/foraneus.rb

@@ -7,58 +7,87 @@ require_relative 'foraneus/converters/noop'
 require_relative 'foraneus/converters/string'
 require_relative 'foraneus/errors'
 
-# Foraneus is library for parsing external data.
-#
-# It allows to define value_sets that specify how the external data is structured
-#   and how it should be parsed.
+# Foraneus base class used to declare a data set, aka 'form'.
 class Foraneus
 
+
+  # @return [Hash] Parsed data.
   attr_accessor :data
 
-  def initialize(data = {})
+  # @api private
+  def initialize
     @data = {}
     @raw_data = {}
 
     @errors = {}
-
-    self.class.send(:__raw, self, data)
   end
 
+  # Declares a boolean field.
+  #
+  # @param [Symbol] name The name of the field.
   def self.boolean(name)
     converter = Foraneus::Converters::Boolean.new
     field(name, converter)
   end
 
+  # Declares a date field.
+  #
+  # @param [Symbol] name The name of the field.
+  # @param (see Foraneus::Converters::Date#initialize)
   def self.date(name, *args)
     converter = Foraneus::Converters::Date.new(*args)
     field(name, converter)
   end
 
+  # Declares a decimal field.
+  #
+  # @param [Symbol] name The name of the field.
+  # @param (see Foraneus::Converters::Decimal#initialize)
   def self.decimal(name, *args)
     converter = Foraneus::Converters::Decimal.new(*args)
     field(name, converter)
   end
 
-  def self.float(name)
-    converter = Foraneus::Converters::Float.new
+  # Declares a float field.
+  #
+  # @param [Symbol] name The name of the field.
+  # @param (see Foraneus::Converters::Float#initialize)
+  def self.float(name, *args)
+    converter = Foraneus::Converters::Float.new(*args)
     field(name, converter)
   end
 
-  def self.integer(name)
-    converter = Foraneus::Converters::Integer.new
+  # Declares an integer field.
+  #
+  # @param [Symbol] name The name of the field.
+  # @param (see Foraneus::Converters::Integer#initialize)
+  def self.integer(name, *args)
+    converter = Foraneus::Converters::Integer.new(*args)
     field(name, converter)
   end
 
+  # Declares a noop field.
+  #
+  # @param [Symbol] name The name of the field.
   def self.noop(name)
     converter = Foraneus::Converters::Noop.new
     field(name, converter)
   end
 
+  # Declares a string field.
+  #
+  # @param [Symbol] name The name of the field.
   def self.string(name)
     converter = Foraneus::Converters::String.new
     field(name, converter)
   end
 
+  # Declares a field.
+  #
+  # When no converter is given, noop is assigned.
+  #
+  # @param [Symbol] name The name of the field.
+  # @param [#parse, #raw] converter The converter.
   def self.field(name, converter = nil)
     converter ||= Foraneus::Converters::Noop.new
 
@@ -66,15 +95,21 @@ class Foraneus
     self.send(:attr_accessor, name)
   end
 
+  # Map of fields and their corresponding converters.
+  #
+  # @return [Hash<String, Converter>]
   def self.fields
     @fields ||= {}
   end
 
+  # Parses data coming from an external source.
+  #
+  # @param [Hash<Symbol, String>] raw_data
+  #
+  # @return [Foraneus] An instance of a form.
   def self.parse(raw_data)
     instance = self.new
 
-    parsed_data = {}
-
     raw_data.each do |k, v|
       __parse_raw_datum(instance, k, v)
     end
@@ -82,37 +117,14 @@ class Foraneus
     instance
   end
 
-  # @param [Foraneus] foraneus
-  # @param [String, Symbol] k
-  # @param [String] v
-  def self.__parse_raw_datum(foraneus, k, v)
-    field = k.to_s
-    converter = fields[field]
-
-    return unless converter
-
-    foraneus[k] = v
-
-    unless v.nil?
-      v = converter.parse(v)
-    end
-
-    foraneus.send("#{field}=", v)
-    foraneus.data[k] = v
-
-  rescue
-    error = Foraneus::Error.new($!.class.name, $!.message)
-    foraneus.instance_variable_get(:@errors)[k] = error
-  end
-  private_class_method :__parse_raw_datum
-
+  # Converts data into an external representation.
+  #
+  # @param [Hash<Symbol, Object>] data
+  #
+  # @return [Foraneus] An instance of a form.
   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)
@@ -130,8 +142,10 @@ class Foraneus
 
     instance
   end
-  private_class_method :__raw
 
+  # @return [Hash] raw data when m == nil.
+  # @return [Array<Error>] errors when m == :errors.
+  # @return [String] raw data value for the field m.
   def [](m = nil)
     if m == :errors
       @errors
@@ -144,11 +158,49 @@ class Foraneus
     end
   end
 
+  # @api private
+  #
+  # Sets a raw value.
+  #
+  # @param [Symbol] k Field name.
+  # @param [String] v Raw value.
   def []=(k, v)
     @raw_data[k] = v
   end
 
+  # Returns true if no conversion errors occurred. false otherwise.
   def valid?
     @errors.empty?
   end
+
+  # @api private
+  #
+  # Parses a raw value and assigns it to the corresponding field.
+  #
+  # It also registers errors if the conversion fails.
+  #
+  # @param [Foraneus] foraneus
+  # @param [String, Symbol] k
+  # @param [String] v
+  def self.__parse_raw_datum(foraneus, k, v)
+    field = k.to_s
+    converter = fields[field]
+
+    return unless converter
+
+    foraneus[k] = v
+
+    unless v.nil?
+      v = converter.parse(v)
+    end
+
+    foraneus.send("#{field}=", v)
+    foraneus.data[k] = v
+
+  rescue
+    error = Foraneus::Error.new($!.class.name, $!.message)
+    foraneus.instance_variable_get(:@errors)[k] = error
+  end
+  private_class_method :__parse_raw_datum
+
 end

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

@@ -44,7 +44,7 @@ describe Foraneus::Converters::Decimal do
     let(:n) { BigDecimal.new('1234567.89') }
 
     it 'returns a decimal representation' do
-      s = '1,234,567.89'
+      s = '1234567.89'
 
       converter.raw(n).should eq(s)
     end

data/spec/lib/foraneus_spec.rb

@@ -10,28 +10,6 @@ describe Foraneus do
     end
   }
 
-  describe '.new' do
-    subject(:form) { form_spec.new }
-
-    its(:delay) { should be_nil }
-
-    its([:delay]) { should be_nil }
-
-    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
     context 'with parseable data' do
       subject(:form) { form_spec.parse(:delay => '5') }

metadata

@@ -1,17 +1,45 @@
 --- !ruby/object:Gem::Specification
 name: foraneus
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
 platform: ruby
 authors:
 - Gianfranco Zas
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-19 00:00:00.000000000 Z
+date: 2014-06-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.14.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.14.0
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='