foraneus 0.0.1

data/COPYING.LESSER

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

data/README.md

@@ -0,0 +1,5 @@
+== .
+Copyright (c) 2012 "snmgian", released under LGPL v3 license. 
+
+== .
+Contact at: snmgian at gmail dot com

data/lib/foraneus/converters.rb

@@ -0,0 +1,50 @@
+require 'delegate'
+
+module Foraneus
+
+  # A converter is intended for parsing a string and returning a value. 
+  module Converters
+
+    # A decorator for concrete converters. It prevents nil values and manages errors raised by {AbstractConverter#parse}
+    class ConverterDecorator < SimpleDelegator
+
+      # @param [AbstractConverter] converter The converter to be decorated
+      def initialize(converter)
+        super(converter)
+        @source = converter
+      end
+
+      # Invokes {AbstractConverter#parse}. Manages errors raised by the converter.
+      # Also, it returns nil if value.nil?
+      # @param [String] value Value to be parsed
+      # @return [Object] Parsed value
+      # @raise [Foraneus::ConverterError] if the concrete converter raises an error
+      def parse(value)
+        return nil if value.nil?
+
+        begin
+          @source.parse(value)
+        rescue
+          raise Foraneus::ConverterError.new(value, @source.name)
+        end
+      end
+    end
+
+    # @abstract Converters should inherit from this class and override #{code_name} and #{parse}
+    class AbstractConverter
+
+      # Returns the of this converter
+      # @return [String]
+      def name
+        raise NotImplementedError
+      end
+
+      # Parses a value and returns the obtained parsed value
+      # @param [String] value Value to be parsed
+      # @return [Object]
+      def parse(value)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/foraneus/errors.rb

@@ -0,0 +1,60 @@
+module Foraneus
+
+  # An error during the parsing of a value.
+  class ValueError
+
+    # @!attribute name
+    #   @return [String] Name of the field value
+    attr_accessor :name
+
+    # @!attribute value
+    #   @return [String] Value attempted to be parsed
+    attr_accessor :value
+
+    # @!attribute expected_type
+    #   @return [String] The expected type to be parsed
+    attr_accessor :expected_type
+
+    # @param [String] name The name of the field in the value_set
+    # @param [String] value The value attempted to be parsed
+    # @param [Symbol] expected_type The expected type to be parsed
+    def initialize(name, value, expected_type)
+      @name = name
+      @value = value
+      @expected_type = expected_type
+    end
+  end
+
+  # Raised on an attempt to create a value_set from invalid value
+  class ValueSetError < StandardError
+
+    # @!attribute value_set
+    #   @return [ValueSet] ValueSet with errors
+    attr_accessor :value_set
+
+    # @param [Foraneus::ValueSet] value_set ValueSet with errors
+    def initialize(value_set)
+      @value_set = value_set
+    end
+  end
+
+  # Raised on an attempt to parse an invalid value
+  class ConverterError < StandardError
+
+    # @!attribute value
+    #   @return [String] Value attempted to be parsed
+    attr_accessor :value
+    
+    # @!attribute value
+    #   @return [String] Name of the converter that raised the error
+    attr_accessor :converter_name
+
+    # @param [String] value The value attempted to be parsed
+    # @param [Symbol] converter_name Name of the converter
+    def initialize(value, converter_name)
+      @value = value
+      @converter_name = converter_name
+    end
+  end
+
+end

data/lib/foraneus/hashlike.rb

@@ -0,0 +1,36 @@
+module Foraneus
+
+  # Adds hash read-only capabilities.
+  module HashlikeValueSet
+    
+    # Returns the value associated with a key
+    #
+    # Possible keys are:
+    #  - valid?
+    #  - errors
+    #  - raw_values
+    #  - as_hash
+    #
+    # @param [Symbol] key The key for the value to retrieve
+    # @return [Object, nil] The value associated with key, or nil if the key is unknown
+    def [](key)
+      ivar = case key
+      when :valid?
+        :@valid
+      when :errors
+        :@errors
+      when :raw_values
+        :@raw_values
+      when :as_hash
+        :@hash_values
+      else
+        nil
+      end
+
+      if ivar
+        self.instance_variable_get(ivar)
+      end
+    end
+  end
+
+end

data/lib/foraneus/markers.rb

@@ -0,0 +1,9 @@
+module Foraneus
+
+  # Marks a value_set as invalid.
+  module InvalidValueSet; end
+
+  # Marks a value_set whose getter methods return raw values.
+  module RawValueSet; end
+
+end

data/lib/foraneus/raw_value_set_builder.rb

@@ -0,0 +1,43 @@
+module Foraneus
+  
+  # Module for building raw value_sets
+  module RawValueSetBuilder
+
+    # Builds a RawValueSet.
+    # @param [Class] form_class A ValueSet class
+    # @param [Hash] meta Meta information about fields and converters
+    # @param [ValueSet, Hash] form_or_params ValueSet or Hash that will be used to build a RawValueSet
+    # @return [RawValueSet]
+    def self.build(form_class, meta, form_or_params)
+      if form_or_params.is_a?(Foraneus::ValueSet)
+        self.raw_form(form_or_params)
+      elsif form_or_params.is_a?(Hash)
+        self.raw_params(form_class, meta, form_or_params)
+      end
+    end
+
+    # Builds a RawValueSet from a ValueSet object
+    # @api private
+    # @param [ValueSet] value_set
+    # @return [RawValueSet]
+    def self.raw_form(value_set)
+      raw_vs_class = Class.new(value_set.class) do
+        include Foraneus::RawValueSet
+      end
+
+      raw_vs = raw_vs_class.new
+      value_set[:raw_values].each do |name, value|
+        raw_vs.instance_variable_set("@#{name}", value)
+      end
+      raw_vs
+    end
+
+    # Builds a value_set and returns a RawValueSet
+    # @api private
+    def self.raw_params(form_class, meta, params)
+      form = Foraneus::ValueSetBuilder.build(form_class, meta, params)
+      raw_form(form)
+    end
+
+  end
+end

data/lib/foraneus/simple_converters.rb

@@ -0,0 +1,79 @@
+require 'delegate'
+
+module Foraneus
+  module Converters
+
+    # Boolean converter. 
+    class Boolean < AbstractConverter
+
+      # @see {AbstractConverter#see}
+      def name
+        :boolean
+      end
+
+      # @see AbstractConverter#parse
+      # @param [String] value The value to be parsed
+      # @return [Boolean] Returns true only if value == 'true'
+      def parse(value)
+        if value == true
+          true
+        elsif value == 'true'
+          true
+        else
+          false
+        end
+      end
+    end
+
+    # Float converter.
+    class Float < AbstractConverter
+
+      # @see {AbstractConverter#see}
+      def name
+        :float
+      end
+
+      # @see AbstractConverter#parse
+      # @return [Float] Returns a float number
+      def parse(value)
+        Kernel.Float(value)
+      end
+    end
+
+    # Integer converter.
+    class Integer < AbstractConverter
+
+      # @see {AbstractConverter#see}
+      def name
+        :integer
+      end
+
+      # @see AbstractConverter#parse
+      # @return [Integer] Returns an integer number
+      def parse(value)
+        Kernel.Integer(value)
+      end
+    end
+
+    # String converter.
+    class String < AbstractConverter
+
+      # @see {AbstractConverter#see}
+      def name
+        :string
+      end
+
+      # @see AbstractConverter#parse
+      # @return [String] Returns a String reprensentation of the given value.
+      def parse(value)
+        if value.is_a?(::String)
+          value
+        else
+          value.to_s
+        end
+      end
+    end
+
+  end
+end
+

data/lib/foraneus/value_set.rb

@@ -0,0 +1,46 @@
+module Foraneus
+
+  # Base class from which all the value_sets should inherit.
+  #
+  # Concrete classes model a set of params/values that are parsed from an external source (like HTTP query params)
+  class ValueSet
+
+    # Builds an instance of ValueSet that conforms with its fields specification.
+    #
+    # If any of the params can be parsed by its corresponding convertor then an
+    # {InvalidValueSet} and {RawValueSet} is returned that holds raw_values
+    #
+    # @param [Hash<Symbol, String>] params Hash that holds values that will be parsed and associated
+    #   with the created ValueSet instance.
+    # @return [ValueSet, InvalidValueSet, RawValueSet] A value_set
+    def self.build(params = {})
+      Foraneus::ValueSetBuilder.build(self, @meta, params)
+    end
+
+    # Builds an instance of ValueSet and raises an {ValueSetError} if invalid params.
+    # @see .build
+    # @param (see .build)
+    def self.build!(params = {})
+      value_set = self.build(params)
+      if value_set.kind_of?(Foraneus::InvalidValueSet)
+        raise Foraneus::ValueSetError.new(value_set)
+      end
+
+      value_set
+    end
+
+    # Returns a {RawValueSet} that corresponds to the given argument.
+    #
+    # @overload raw(value_set)
+    #   @param [ValueSet] value_set ValueSet whose raw value will be used to create a {RawValueSet}
+    #
+    # @overload raw(params)
+    #   @param [Hash] params Params for creating a {RawValueSet}
+    #
+    # @return [RawValueSet]
+    def self.raw(vs_or_params)
+      Foraneus::RawValueSetBuilder.build(self, @meta, vs_or_params)
+    end
+
+  end
+end

data/lib/foraneus/value_set_builder.rb

@@ -0,0 +1,132 @@
+module Foraneus
+
+  # Module for building value_sets
+  module ValueSetBuilder
+
+    # Builds an instance of a value_set
+    #
+    # @param [Class<? extends ValueSet>] vs_class ValueSet subclass from with the value_set will be instantiated
+    #
+    # @param [Hash<Symbol, Symbol>] meta Hash with metainformation. Each key is a field name, and each value is the name of the converter to be used
+    #
+    # @param [Hash<Symbol, Object>] params Parameters that will be parsed and set as attributes for the newly value_set
+    #
+    # @return [ValueSet] An instance of (or an instance of subclass of) vs_class
+    def self.build(vs_class, meta, params = {})
+
+      parsed_params, raw_params, errors = self.parse_params(meta, params)
+
+      if errors.empty?
+        form = vs_class.new
+        set_instance_vars(form, parsed_params)
+        form.instance_variable_set(:@hash_values, parsed_params)
+      else
+        form = create_invalid_value_set(vs_class)
+        set_instance_vars(form, raw_params)
+      end
+
+      form.instance_variable_set(:@valid, errors.empty?)
+      form.instance_variable_set(:@errors, errors)
+      form.instance_variable_set(:@raw_values, raw_params)
+      form
+    end
+
+    # Creates a value_set marked as invalid.
+    #
+    # It creates a value set by creating an instance from a subclass of vs_class.
+    # That subclass is mixed in with {InvalidValueSet} and {RawValueSet}
+    #
+    # @api private
+    #
+    # @param [Class<? extends ValueSet>] vs_class Subclass of ValueSet from which the invalid value_set
+    #   will be instantiated
+    #
+    # @return [ValueSet] A kind of ValueSet, mixed with {InvalidValueSet} and {RawValueSet}
+    def self.create_invalid_value_set(vs_class)
+      form_class = Class.new(vs_class) do
+        include Foraneus::InvalidValueSet
+        include Foraneus::RawValueSet
+      end
+      form = form_class.new
+    end
+
+    # Parses a given value.
+    #
+    # The converter is selected by querying the given metadata, searching for the given name.
+    # @api private
+    #
+    # @param [Hash<Symbol, Symbol>] meta (see .build)
+    # @param [Symbol] name Name of the field to be parsed
+    # @param [String] value Value to be parsed
+    #
+    # @return [Array] An array of two elements. The first of them is the result of the parsing, 
+    #   and the last one is a boolean value that indicates if an error occured during the parsing.
+    def self.parse(meta, name, value)
+      parsed_value = nil
+      error = false
+
+      parser_code = meta[name]
+      parser = Foraneus.registry[parser_code]
+
+      begin
+        parsed_value = parser.parse(value)
+      rescue StandardError => e
+        error = true
+      end
+
+      [parsed_value, error]
+    end
+
+    # Parses each of the given params. 
+    #
+    # The converter is select by searching for the param name in the metadata.
+    # If a param is not expected by the metadata, then it is simply ignored.
+    #
+    # @api private
+    #
+    # @param [Hash<Symbol, Symbol>] meta (see .build)
+    # @param [Hash<Symbol, Object>] params (see .build)
+    #
+    # @return [Array] An array consisting of three elements:
+    #   - Hash { Symbol => Object } Parsed params/values
+    #   - Hash { Symbol => Object } Given params/values, it only contains params that are present in the metadata.
+    #   - Hash { Symbol => {ValueError} } Errors ocurred during parsing, each key is the name of a field with an associated error
+    def self.parse_params(meta, params)
+      parsed_params = {}
+      raw_params = {}
+      errors = {}
+
+      params.each do |name, value|
+        normalized_name = name.to_sym
+        next unless meta.include?(normalized_name)
+
+        raw_params[name] = value
+        parsed_value, error = self.parse(meta, normalized_name, value)
+        unless error
+          parsed_params[normalized_name] = parsed_value
+        else
+          errors[normalized_name] = Foraneus::ValueError.new(normalized_name, value, meta[normalized_name])
+        end
+      end
+
+      [parsed_params, raw_params, errors]
+    end
+
+    # Sets instance variables to an object.
+    #
+    # @api private
+    #
+    # @param [Object] o The object to set the instance variables
+    # @param [Hash<Symbol, Object>] params A hash with the names and values of instance variables that will be set.
+    #
+    # @return [Object] The received object with the instance variables set
+    def self.set_instance_vars(o, params)
+      params.each do |name, value|
+        o.instance_variable_set("@#{name}", value)
+      end
+
+      o
+    end
+
+  end
+end

data/lib/foraneus.rb

@@ -0,0 +1,57 @@
+# Foraneus is library for parsing external data.
+#
+# It allows to define value_sets that specify how the external data is structured and how should be parsed.
+module Foraneus
+
+  @registry = {}
+
+  # Returns the converters registry
+  # @return [Hash<Symbol, ConverterDecorator>] A hash of registered converters
+  def self.registry
+    @registry
+  end
+
+  # Registers a converter.
+  #
+  # @param [Class<? extends Converters::AbstractConverter>] converter_class The converter
+  def self.register(converter_class)
+
+    decorated = Converters::ConverterDecorator.new(converter_class.new)
+    @registry[decorated.name] = decorated 
+
+    self.define_type_method(decorated.name)
+  end
+
+  # Defines a class method in {ValueSet} that corresponds to a converter.
+  #
+  # The defined method will be invoked when defining a value_set
+  #
+  # @api private
+  #
+  # @param [String] name The name of the converter
+  def self.define_type_method(name)
+    Foraneus::ValueSet.singleton_class.send :define_method, name do |field|
+      self.send :attr_reader, field
+
+      @meta ||= {}
+      @meta[field] = name
+    end
+  end
+
+end
+
+[
+  :converters,
+  :errors,
+  :hashlike,
+  :markers,
+  :simple_converters,
+  :raw_value_set_builder,
+  :value_set,
+  :value_set_builder,
+].each { |f| require_relative "foraneus/#{f}" }
+
+Foraneus.register(Foraneus::Converters::Boolean)
+Foraneus.register(Foraneus::Converters::Float)
+Foraneus.register(Foraneus::Converters::Integer)
+Foraneus.register(Foraneus::Converters::String)