organ 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8033a1f23ace0b7e8ba5b04ecbf34b842f6bb1bc
+  data.tar.gz: edc103641da1a031b8ffec33070aa49ae88fd13a
+SHA512:
+  metadata.gz: ce1a123bbb939f0f28efbade808bcefd58a7151fdab8ebbc2588e533d03fb5d3f9c496f2be01a6cd9013ff26286b992b4f60c69d11163e85340bb4e3b8938ab9
+  data.tar.gz: cd965088fc635e7421658cffda80367d80be5d17fc94b64a46e9943e7eb8b14a34386de8c2326df7cfc1973c11f4172c359fb1fe737437ec2b89edd5abdb168d

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Sebastian Borrazas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,321 @@
+Organ
+=====
+
+Forms with integrated validations and attribute coercing.
+
+Introduction
+-----------
+
+Organ is a small library for manipulating form-based data with validations
+attributes coercion.
+
+These forms are very useful for handling HTTP requests where we receive certain
+parameters and need to coerce them, validate them and then do something with
+them. They are made so that the system has 1 form per service, so the form
+names should usually be very explicit of the service they are providing
+(`CreateUser`, `DeleteUser`, `SendTweet`, `NotifyAdmin`).
+
+You should reuse forms behaviour (including validations) through inheritance
+or modules (like having `CreateUser` inherit from `UpdateUser`). They can be
+extended to handle worker jobs, to act as presenters, etc.
+
+They do not handle HTML rendering of forms or do any HTTP manipulation.
+
+The name `Organ` was inspired by the fact that organs beheave in a module manner
+so that they do one thing only.
+
+Usage
+-----
+
+A form is simply a class which inherits from `Organ::Form`. You can specify
+the attributes the form will have with the `attributes` class method.
+
+The `attributes` class method takes the attribute name and any options that
+attribute has.
+
+The options can be:
+
+* `:type` - The type for which that attribute will be coerced.
+* `:skip` - If `true` it won't include the attribute when calling the
+  `#attributes` method on the instance.
+* `:skip_reader` - If `true`, it won't create the attribute reader for that
+  attribute.
+
+Example:
+
+```ruby
+class CreateCustomer < Organ::Form
+
+  attribute(:name, :type => :string, :trim => true)
+  attribute(:address, :type => :string, :trim => true)
+
+  def validate
+    validate_presence(:name)
+    validate_length(:name, :min => 4, :max => 255)
+    validate_length(:address, :max => 255)
+
+    validate_uniqueness(:address) do |addr|
+      Customer.where(:address => addr).empty?
+    end
+  end
+
+  def perform
+    Customer.create(attributes)
+  end
+
+end
+
+# Sinatra example
+post "/customer" do
+  form = CreateCustomer.new(params[:customer])
+  content_type(:json)
+  if form.valid?
+    form.perform
+    status(204)
+  else
+    status(422)
+    JSON.generate("errors" => form.errors)
+  end
+end
+```
+
+Default types
+-------------
+
+The default types you can use are:
+
+### :string
+
+Coerces the value into a string or nil if no value given. If the `:trim` option
+is given it also strips the preceding/trailing whitespaces and newlines.
+
+### :boolean
+
+Coerces the value into false (if no value given) or true otherwise.
+
+### :array
+
+Coerces the value into an Array. If it can't be coerced into an Array, it
+returns an empty Array. An additional `:element_type` option with another type
+can be specifed to coerce all the elements of the array into it.
+
+If a Hash is passed instead of an array, it takes the Hash values.
+
+### :float
+
+Coerce the value into a Float, or nil of the value can't be coerced into a
+float.
+
+### :hash
+
+Coerces the value into a Hash. If it can't be coerced into a Hash, it returns
+an empty Hash. An additional `:key_type` and/or `:value_type` can be specified
+to coerce the keys/values of the hash respectively.
+
+### :integer
+
+Coerces the value into a Fixnum. If it can't be coerced it returns nil.
+
+### :date
+
+Coerces the value into a date. If the value doesn't have the `%Y-%m-%d` format
+it returns nil.
+
+Default validations
+-------------------
+
+### validate_presence
+
+If the value is falsy or an empty string it appends a `:blank` error to the
+attribute.
+
+### validate_uniqueness
+
+If the value is present and the block passed returns false, it appends a
+`:taken` error to the attribute. Example:
+
+```ruby
+validate_uniqueness(:username) do |username|
+  User.where(:username => username).empty?
+end
+```
+
+### validate_email_format
+
+If the value is present and doesn't match an emails format, it appends an
+`:invalid` error to the attribute.
+
+### validate_format
+
+If the value is present and doesn't match the specified format, it appends an
+`:invalid` error to the attribute.
+
+### validate_length
+
+If the value is present and shorter than the `:min` option, it appends a
+`:too_short` error to the attribute. If it's longer than the `:max` option, it
+appends a `:too_long` error to the attribute. Example:
+
+```ruby
+validate_length(:username, :min => 3, :max => 255)
+validate_length(:first_name, :max => 255)
+```
+
+### validate_inclusion
+
+If the value is present and not included on the given list it appends a
+`:not_included` error to the attribute.
+
+### validate_range
+
+If the value is present and less than the `:min` option, it appends a
+`:less_than` error to the attribute. If it's greater than the `:max` option, it
+appends a `:greater_than` error to the attribute. Example:
+
+```ruby
+validate_range(:age, :min => 18)
+```
+
+Extensions
+----------
+
+These forms were meant to be extended when necessary. These are a few examples
+of how they can be extended.
+
+### Extensions::Paginate
+
+An extension to paginate results with Sequel Datasets.
+
+```ruby
+module Extensions
+  module Presenter
+
+    DEFAULT_PER_PAGE = 30
+    MAX_PER_PAGE = 100
+
+    def self.included(base)
+      base.attribute(:page, :type => :integer, :skip_reader => true)
+      base.attribute(:per_page, :type => :integer, :skip_reader => true)
+    end
+
+    def each(&block)
+      results.each(&block)
+    end
+
+    def total_pages
+      @total_pages ||= (1.0 * dataset.count / per_page).ceil
+    end
+
+    def any?
+      total_pages > 0
+    end
+
+    def results
+      @results ||= begin
+        start = (page - 1) * per_page
+        _dataset = dataset.limit(per_page, start)
+        _dataset.all
+      end
+    end
+
+    def per_page
+      if @per_page && @per_page >= 1 && per_page <= MAX_PER_PAGE
+        @per_page
+      else
+        DEFAULT_PER_PAGE
+      end
+    end
+
+    def page
+      @page && @page > 1 ? @page : 1
+    end
+
+  end
+end
+
+module Presenters
+  class UserPets < Organ::Form
+
+    include Extensions::Paginate
+
+    attribute(:user_id, :type => :integer)
+
+    def dataset
+      Pet.where(:user_id => user_id)
+    end
+
+  end
+end
+
+# Sinatra app
+get "/pets" do
+  presenter = Presenter::UserPets.new({
+    :user_id => session[:user_id],
+    :page => params[:page],
+    :per_page => params[:per_page]
+  })
+  erb(:"pets/index", :locals => { :pets => presenter })
+end
+```
+
+### Extensions::Worker
+
+An extension to create worker job handlers using
+[Ost](https://github.com/soveran/ost).
+
+```ruby
+module Extensions
+  module Worker
+
+    def self.queue_job(attributes)
+      queue << JSON.generate(attributes)
+    end
+
+    def self.stop
+      queue.stop
+    end
+
+    def self.watch_queue
+      queue.each do |json_str|
+        attributes = JSON.parse(json_str)
+        new(attributes).perform
+      end
+    end
+
+    private
+
+    def self.queue
+      Ost[self.name]
+    end
+
+  end
+end
+
+module Workers
+  class EmailNotifier < Organ::Form
+
+    include Extensions::Worker
+
+    attribute(:email)
+    attribute(:message)
+
+    def perform
+      # send message to email...
+    end
+
+  end
+end
+
+# Sinatra app
+get "/queue_email" do
+  Workers::EmailNotifier.queue_job(params[:notification])
+  status(204)
+end
+```
+
+Aknowledgements
+---------------
+
+This library was inspired mainly by @soveran
+[Scrivener](https://github.com/soveran/scrivener) and was made with the help ofn
+@grilix.

data/Rakefile

@@ -0,0 +1,7 @@
+require "rake/testtask"
+
+desc "Run all tests"
+Rake::TestTask.new(:test) do |t|
+  t.pattern = "./spec/**/*_spec.rb"
+  t.verbose = false
+end

data/lib/organ.rb

@@ -0,0 +1,7 @@
+require_relative "organ/form"
+
+module Organ
+
+  VERSION = "0.0.1"
+
+end

data/lib/organ/coercer.rb

@@ -0,0 +1,136 @@
+module Organ
+  module Coercer
+
+    # Coerce the value into a String or nil if no value given.
+    #
+    # @param value [Object]
+    # @option options [Boolan] :trim (false)
+    #   If true, it strips the preceding/trailing whitespaces and newlines.
+    #   It also replaces multiple consecutive spaces into one.
+    #
+    # @return [String, nil]
+    #
+    # @api semipublic
+    def coerce_string(value, options = {})
+      value = value ? value.to_s : nil
+      if value && options[:trim]
+        value = value.strip.gsub(/\s{2,}/, " ")
+      end
+      value
+    end
+
+    # Corce the value into true or false.
+    #
+    # @param value [Object]
+    #
+    # @return [Boolean]
+    #
+    # @api semipublic
+    def coerce_boolean(value, options = {})
+      !!value
+    end
+
+    # Coerce the value into an Array.
+    #
+    # @param value [Object]
+    #   The value to be coerced.
+    # @option options [Symbol] :element_type (nil)
+    #   The type of the value to coerce each element of the array. No coercion
+    #   done if type is nil.
+    #
+    # @return [Array]
+    #   The coerced Array.
+    #
+    # @api semipublic
+    def coerce_array(value, options = {})
+      element_type = options[:element_type]
+      value = value.values if value.kind_of?(Hash)
+      if value.kind_of?(Array)
+        if element_type
+          value.map do |array_element|
+            send("coerce_#{element_type}", array_element)
+          end
+        else
+          value
+        end
+      else
+        []
+      end
+    end
+
+    # Coerce the value into a Float.
+    #
+    # @param value [Object]
+    #
+    # @return [Float, nil]
+    #
+    # @api semipublic
+    def coerce_float(value, options = {})
+      Float(value) rescue nil
+    end
+
+    # Coerce the value into a Hash.
+    #
+    # @param value [Object]
+    #   The value to be coerced.
+    # @option options :key_type [Symbol] (nil)
+    #   The type of the hash keys to coerce, no coersion done if type is nil.
+    # @options options :value_type [Symbol] (nil)
+    #   The type of the hash values to coerce, no coersion done if type is nil.
+    #
+    # @return [Hash]
+    #   The coerced Hash.
+    #
+    # @api semipublic
+    def coerce_hash(value, options = {})
+      key_type = options[:key_type]
+      value_type = options[:value_type]
+      if value.kind_of?(Hash)
+        value.each_with_object({}) do |(key, value), coerced_hash|
+          key = send("coerce_#{key_type}", key) if key_type
+          value = send("coerce_#{value_type}", value) if value_type
+          coerced_hash[key] = value
+        end
+      else
+        {}
+      end
+    end
+
+    # Coerce the value into an Integer.
+    #
+    # @param value [Object]
+    #   The value to be coerced.
+    #
+    # @return [Integer, nil]
+    #   An Integer if the value can be coerced or nil otherwise.
+    #
+    # @api semipublic
+    def coerce_integer(value, options = {})
+      value = value.to_s
+      if value.match(/\A0|[1-9]\d*\z/)
+        value.to_i
+      else
+        nil
+      end
+    end
+
+    # Coerce the value into a Date.
+    #
+    # @param value [Object]
+    #   The value to be coerced.
+    #
+    # @return [Date, nil]
+    #   A Date if the value can be coerced or nil otherwise.
+    #
+    # @api semipublic
+    def coerce_date(value, options = {})
+      value = coerce(value, String)
+      begin
+        Date.strptime(value, "%Y-%m-%d")
+      rescue ArgumentError
+        nil
+      end
+    end
+
+  end
+end

data/lib/organ/form.rb

@@ -0,0 +1,131 @@
+require_relative "validation_error"
+require_relative "validations"
+require_relative "coercer"
+
+module Organ
+  # Form for doing actions based on the attributes specified.
+  # This class has to be inherited by different forms, each performing a
+  # different action. If validations are needed, #validate method should be
+  # overridden.
+  #
+  # @example
+  #
+  #   class LoginForm < Organ::Form
+  #
+  #     attribute(:username, :type => :string)
+  #     attribute(:password, :type => :string)
+  #
+  #     def validate
+  #       unless valid_login?
+  #         append_error(:username, :invalid)
+  #       end
+  #     end
+  #
+  #     private
+  #
+  #     def valid_login?
+  #       user = User.where(username: username).first
+  #       user && check_password_secure(user.password, password)
+  #     end
+  #
+  #   end
+  #
+  class Form
+
+    include Organ::Validations
+    include Organ::Coercer
+
+    # Copy parent attributes to inherited class.
+    #
+    # @param klass [Class]
+    #
+    # @api private
+    def self.inherited(klass)
+      super(klass)
+      klass.instance_variable_set(:@attributes, attributes.dup)
+    end
+
+    # Define an attribute for the form.
+    #
+    # @param name
+    #   The Symbol attribute name.
+    # @option options [Symbol] :type (nil)
+    #   The type of this attribute.
+    # @option options [Symbol] :skip_reader (false)
+    #   If true, skips from creating the attribute reader.
+    #
+    # @api public
+    def self.attribute(name, options = {})
+      attr_reader(name) unless options[:skip_reader]
+      define_method("#{name}=") do |value|
+        if options[:type]
+          value = send("coerce_#{options[:type]}", value, options)
+        end
+        instance_variable_set("@#{name}", value)
+      end
+      attributes[name] = options
+    end
+
+    # Retrieve the list of attributes of the form.
+    #
+    # @return [Hash]
+    #   The class attributes hash.
+    #
+    # @api private
+    def self.attributes
+      @attributes ||= {}
+    end
+
+    # Initialize a new Form::Base form.
+    #
+    # @param attrs [Hash]
+    #   The attributes values to use for the new instance.
+    #
+    # @api public
+    def initialize(attrs = {})
+      set_attributes(attrs)
+    end
+
+    # Set the attributes belonging to the form.
+    #
+    # @param attrs [Hash<String, Object>]
+    #
+    # @api public
+    def set_attributes(attrs)
+      return unless attrs.kind_of?(Hash)
+
+      attrs = coerce_hash(attrs, :key_type => :string)
+
+      self.class.attributes.each do |attribute_name, _|
+        send("#{attribute_name}=", attrs[attribute_name.to_s])
+      end
+    end
+
+    # Get the all attributes with its values of the current form.
+    #
+    # @return [Hash<Symbol, Object>]
+    #
+    # @api public
+    def attributes
+      self.class.attributes.each_with_object({}) do |(name, opts), attrs|
+        attrs[name] = send(name) unless opts[:skip]
+      end
+    end
+
+    # Validate and perform the form actions. If any errors come up during the
+    # validation or the #perform method, raise an exception with the errors.
+    #
+    # @raise [Organ::ValidationError]
+    #
+    # @api public
+    def perform!
+      if valid?
+        perform
+      end
+      if errors.any?
+        raise Organ::ValidationError.new(errors)
+      end
+    end
+
+  end
+end

data/lib/organ/validation_error.rb

@@ -0,0 +1,20 @@
+module Organ
+  class ValidationError < StandardError
+
+    # !@attribute [r] errors
+    #   @return [Hash<Symbol, Array>]
+    #
+    # @api public
+    attr_reader :errors
+
+    # Initialize the Organ::ValidationError.
+    #
+    # @param errors [Hash<Symbol, Array>]
+    #
+    # @api public
+    def initialize(errors)
+      @errors = errors
+    end
+
+  end
+end

data/lib/organ/validations.rb

@@ -0,0 +1,161 @@
+module Organ
+  module Validations
+
+    EMAIL_FORMAT = /\A
+      ([0-9a-zA-Z\.][-\w\+\.]*)@
+      ([0-9a-zA-Z_][-\w]*[0-9a-zA-Z]\.)+[a-zA-Z]{2,9}\z/x
+
+    # Get the current form errors Hash.
+    #
+    # @return [Hash<Symbol, Array<Symbol>]
+    #   The errors Hash, having the Symbol attribute names as keys and an
+    #   array of errors (Symbols) as the value.
+    #
+    # @api public
+    def errors
+      @errors ||= Hash.new { |hash, key| hash[key] = [] }
+    end
+
+    # Determine if current form instance is valid by running the validations
+    # specified on #validate.
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def valid?
+      errors.clear
+      validate
+      errors.empty?
+    end
+
+    # Append an error to the given attribute.
+    #
+    # @param attribute_name [Symbol]
+    # @param error [Symbol]
+    #   The error identifier.
+    #
+    # @api public
+    def append_error(attribute_name, error)
+      errors[attribute_name] << error
+    end
+
+    # Validate the presence of the attribute value. If the value is nil or
+    # false append a :blank error to the attribute.
+    #
+    # @param attribute_name [Symbol]
+    #
+    # @api public
+    def validate_presence(attribute_name)
+      value = send(attribute_name)
+      if !value || value.to_s.empty?
+        append_error(attribute_name, :blank)
+      end
+    end
+
+    # Validate the uniqueness of the attribute value. The uniqueness is
+    # determined by the block given. If the value is not unique, append the
+    # :taken error to the attribute.
+    #
+    # @param attribute_name [Symbol]
+    # @param block [Proc]
+    #   A block to determine if a given value is unique or not. It receives
+    #   the value and should return true if the value is unique.
+    #
+    # @api public
+    def validate_uniqueness(attribute_name, &block)
+      value = send(attribute_name)
+      unless block.call(value)
+        append_error(attribute_name, :taken)
+      end
+    end
+
+    # Validate the email format. If the value does not match the email format,
+    # append the :invalid error to the attribute.
+    #
+    # @param attribute_name [Symbol]
+    #
+    # @api public
+    def validate_email_format(attribute_name)
+      validate_format(attribute_name, EMAIL_FORMAT)
+    end
+
+    # Validate the format of the attribute value. If the value does not match
+    # the regexp given, append :invalid error to the attribute.
+    #
+    # @param attribute_name [Symbol]
+    # @param format [Regexp]
+    #
+    # @api public
+    def validate_format(attribute_name, format)
+      value = send(attribute_name)
+      if value && !(format =~ value)
+        append_error(attribute_name, :invalid)
+      end
+    end
+
+    # Validate the length of a String, Array or any other form attribute which
+    # responds to #size. If the value is too short, append the :too_short
+    # error to the attribute. If the value is too long append the :too_long
+    # error to the attribute.
+    #
+    # @param attribute_name [Symbol]
+    # @option options [Integer, nil] :min (nil)
+    # @option options [Integer, nil] :max (nil)
+    #
+    # @api public
+    def validate_length(attribute_name, options = {})
+      min = options.fetch(:min, nil)
+      max = options.fetch(:max, nil)
+      value = send(attribute_name)
+
+      if value
+        length = value.size
+        if min && length < min
+          append_error(attribute_name, :too_short)
+        end
+        if max && length > max
+          append_error(attribute_name, :too_long)
+        end
+      end
+    end
+
+    # Validate the value of the given attribute is included in the list. If
+    # the value is not included in the list, append the :not_included error to
+    # the attribute.
+    #
+    # @param attribute_name [Symbol]
+    # @param attribute_name [Symbol]
+    # @param list [Array]
+    #
+    # @api public
+    def validate_inclusion(attribute_name, list)
+      value = send(attribute_name)
+      if value && !list.include?(value)
+        append_error(attribute_name, :not_included)
+      end
+    end
+
+    # Validate the range in which the attribute can be. If the value is less
+    # than the min a :less_than_min error will be appended. If the value is
+    # greater than the max a :greater_than_max error will be appended.
+    #
+    # @param attribute_name [Symbol]
+    # @option options [Integer] :min (nil)
+    #   The minimum value the attribute can take, if nil, no validation is made.
+    # @option options [Integer] :max (nil)
+    #   The maximum value the attribute can take, if nil, no validation is made.
+    #
+    # @api public
+    def validate_range(attribute_name, options = {})
+      value = send(attribute_name)
+
+      return unless value
+
+      min = options.fetch(:min, nil)
+      max = options.fetch(:max, nil)
+      append_error(attribute_name, :less_than) if min && value < min
+      append_error(attribute_name, :greater_than) if max && value > max
+    end
+
+  end
+end

data/organ.gemspec

@@ -0,0 +1,21 @@
+Gem::Specification.new do |s|
+  s.name = "organ"
+  s.version = "0.0.1"
+  s.summary = "Forms with integrated validations and attribute coercing."
+  s.description = "A small library for manipulating form-based data with validations and attributes coercion."
+  s.authors = ["Sebastian Borrazas"]
+  s.email = ["seba.borrazas@gmail.com"]
+  s.homepage = "http://github.com/sborrazas/organ"
+
+  s.files = Dir[
+    "LICENSE",
+    "CHANGELOG",
+    "README.md",
+    "Rakefile",
+    "lib/**/*.rb",
+    "*.gemspec",
+    "test/*.*"
+  ]
+
+  s.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: organ
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Sebastian Borrazas
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-05-14 00:00:00.000000000 Z
+dependencies: []
+description: A small library for manipulating form-based data with validations and
+  attributes coercion.
+email:
+- seba.borrazas@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- lib/organ.rb
+- lib/organ/coercer.rb
+- lib/organ/form.rb
+- lib/organ/validation_error.rb
+- lib/organ/validations.rb
+- organ.gemspec
+homepage: http://github.com/sborrazas/organ
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.0
+signing_key: 
+specification_version: 4
+summary: Forms with integrated validations and attribute coercing.
+test_files: []