riveter 0.0.1

data/lib/riveter/command_controller.rb

@@ -0,0 +1,93 @@
+module Riveter
+  module CommandController
+    extend ActiveSupport::Concern
+
+    # FIXME: provide ability to define more than one command per controller
+
+    included do
+      class << self
+        #
+        # configures the controller for the given command
+        #
+        # you must provide an `on_success` method and optionally an `on_failure` method which will
+        # receive callbacks when the 'create' action is run
+        #
+        # options supported include:
+        #
+        #   :as               defines the name of the form used to access the params
+        #                     defaults to the name of the command
+        #
+        #   :new_action       overrides the new action name
+        #                     by default it is "new"
+        #
+        #   :create_action    overrides the create action name
+        #                     by default it is "create"
+        #
+        #   :attributes       the list of permitted attributes for initializing the command instance
+        #                     defaults to the attributes defined using the `attr_*` helper methods
+        #
+        def command_controller_for(command_class, options={})
+          raise ArgumentError, "#{command_class.name} does not include #{Command.name} module or inherit from #{Command::Base.name}" unless command_class.ancestors.include?(Command)
+
+          options = {
+            :as => command_class.name.underscore.gsub(/_command$/, ''),
+            :attributes => command_class.attributes,
+            :new_action => :new,
+            :create_action => :create
+          }.merge(options)
+
+          # define instance methods
+          # which provide access to the given
+          # command class and the options
+          define_method :command_class do
+            command_class
+          end
+
+          define_method :command_options do
+            options
+          end
+
+          # define the 'new' and 'create' actions
+          class_eval <<-RUBY
+            def #{options[:new_action]}
+              @command = create_command
+            end
+
+            def #{options[:create_action]}
+              @command = create_command
+              if result = @command.submit(command_params)
+                on_success(@command, result)
+              else
+                self.respond_to?(:on_failure) ? on_failure(@command) : render(:new)
+              end
+            end
+          RUBY
+
+          self.include ActionsAndSupport
+        end
+      end
+    end
+
+    module ActionsAndSupport
+      extend ActiveSupport::Concern
+
+      included do
+        # define the on success callback
+        # method as a placeholder to ensure
+        # implementors provide the method in their classes
+        def on_success(command, result)
+          raise NotImplementedError
+        end
+
+        def create_command
+          command_class.new()
+        end
+
+        def command_params
+          params.require(command_options[:as])
+            .permit(*command_options[:attributes])
+        end
+      end
+    end
+  end
+end

data/lib/riveter/command_routes.rb

@@ -0,0 +1,73 @@
+require 'action_dispatch'
+
+module Riveter
+  module CommandRoutes
+
+    #
+    # defines a route for the given command
+    #
+    # by convention, the word "command" is omitted
+    # from the name of the command
+    #
+    # options include:
+    #
+    #   :path            overrides the path used.
+    #                    by default it is "<command>_command".
+    #                    E.g. for :create_portfolio the path is 'create_portfolio'
+    #
+    #   :controller      overrides the controller used.
+    #                    by default it is "<command>_command_controller"
+    #
+    #   :as              overrides the name of the route generated.
+    #                    by default it is "<command>_command"
+    #
+    #   :new_action      overrides the new action name
+    #                    by default it is "new"
+    #
+    #   :create_action   overrides the create action name
+    #                    by default it is "create"
+    #
+    # E.g.
+    #
+    #   command :create_portfolio
+    #
+    #     creates a route 'create_portfolio' named `create_portfolio_command` to the
+    #     `CreatePortfolioCommandController` controller for the 'new' and 'create' actions
+    #
+    #   command :create_portfolio, :as => 'new_portfolio'
+    #
+    #     creates a route 'create_portfolio' named `new_portfolio` to the
+    #     `CreatePortfolioCommandController` controller for the 'new' and 'create' actions
+    #
+    #   command :create_portfolio, :path => '/define_portfolio'
+    #
+    #     creates a route 'define_portfolio' named `create_portfolio_command` to the
+    #     `CreatePortfolioCommandController` controller for the 'new' and 'create' actions
+    #
+    #   command :create_portfolio, :controller => 'my_portfolio_controller'
+    #
+    #     creates a route 'create_portfolio' named `create_portfolio_command` to the
+    #     `MyPortfolioController` controller for the 'new' and 'create' actions
+    #
+    def command(command, options={})
+      raise ArgumentError, 'Expects a symbol for the command.' unless command.is_a?(Symbol)
+
+      path = options.delete(:path) || command.to_s
+      new_action = options.delete(:new_action) || :new
+      create_action = options.delete(:create_action) || :create
+
+      options = {
+        :controller => :"#{command}_command",
+        :as => :"#{command}_command"
+      }.merge(options)
+
+      # define GET 'new' route
+      get path, options.merge(:action => new_action)
+
+      # define POST 'create' route
+      post path, options.merge(:action => create_action, :as => nil)
+    end
+  end
+end
+
+ActionDispatch::Routing::Mapper.send :include, Riveter::CommandRoutes

data/lib/riveter/core_extensions.rb

@@ -0,0 +1,246 @@
+module Riveter
+  module CoreExtensions
+    module BooleanSupport
+      extend ActiveSupport::Concern
+
+      Booleans = ['yes', 'on', 'true', 'y', '1', 1, true]
+
+      def boolean?
+        self.is_a?(TrueClass) || self.is_a?(FalseClass)
+      end
+
+      def to_b
+        Booleans.include?(self.to_s.downcase)
+      end
+    end
+
+    module DateExtensions
+      extend ActiveSupport::Concern
+
+      def to_utc_ticks
+        Time.utc(self.year, self.month, self.day).to_i * 1000
+      end
+
+      module ClassMethods
+        def system_start_date
+          self.new(1970, 1, 1)
+        end
+
+        def from_utc_ticks(ticks)
+          (DateTime.strptime ticks.to_s, "%Q").to_date
+        end
+      end
+    end
+
+    module ArrayExtensions
+      extend ActiveSupport::Concern
+
+      def cumulative_sum
+        sum = 0
+        self.map {|x| sum += x}
+      end
+
+      # pure genious
+      def nil_sum(identity = nil, &block)
+        if block_given?
+          self.inject(identity) {|sum, x|
+            ((sum || 0) + (yield(x) || 0)) || sum
+          }
+        else
+          self.inject(identity) {|sum, x|
+            ((sum || 0) + (x || 0)) || sum
+          }
+        end
+      end
+
+      # average of a set of numbers
+      def average
+        self.sum / self.length.to_f
+      end
+
+      # variance of a set of numbers
+      def variance
+        avg = self.average
+        self.inject(0.0) {|acc, value| acc + ((value - avg)**2) } / (self.length.to_f - 1)
+      end
+
+      # standard deviation of an array of numbers
+      def standard_deviation
+        Math.sqrt(self.variance)
+      end
+
+      # returns a hash of the items, indexed by the given items attribute
+      def to_hash_for(&block)
+        if block_given?
+          self.inject({}) do |hash, record|
+            hash[yield(record)] = record
+            hash
+          end
+        else
+          self.inject({}) do |hash, record|
+            hash[record] = record
+            hash
+          end
+        end
+      end
+
+      # rounds each items to the specified number of places
+      def round(places)
+        self.collect {|x| x.round(places) }
+      end
+
+      # make compatible with an ActiveRelation
+      def find_each_with_order(&block)
+        self.each &block if block_given?
+      end
+
+      alias_method :find_each, :find_each_with_order
+    end
+
+    module HashExtensions
+      #
+      # = Hash Recursive Merge
+      #
+      # Merges a Ruby Hash recursively, Also known as deep merge.
+      # Recursive version of Hash#merge and Hash#merge!.
+      #
+      # Category::    Ruby
+      # Package::     Hash
+      # Author::      Simone Carletti <weppos@weppos.net>
+      # Copyright::   2007-2008 The Authors
+      # License::     MIT License
+      # Link::        http://www.simonecarletti.com/
+      # Source::      http://gist.github.com/gists/6391/
+      #
+      # Adds the contents of +other_hash+ to +hsh+,
+      # merging entries in +hsh+ with duplicate keys with those from +other_hash+.
+      #
+      # Compared with Hash#merge!, this method supports nested hashes.
+      # When both +hsh+ and +other_hash+ contains an entry with the same key,
+      # it merges and returns the values from both arrays.
+      #
+      #    h1 = {"a" => 100, "b" => 200, "c" => {"c1" => 12, "c2" => 14}}
+      #    h2 = {"b" => 254, "c" => 300, "c" => {"c1" => 16, "c3" => 94}}
+      #    h1.rmerge!(h2)   #=> {"a" => 100, "b" => 254, "c" => {"c1" => 16, "c2" => 14, "c3" => 94}}
+      #
+      # Simply using Hash#merge! would return
+      #
+      #    h1.merge!(h2)    #=> {"a" => 100, "b" = >254, "c" => {"c1" => 16, "c3" => 94}}
+      #
+      def rmerge!(other_hash)
+        merge!(other_hash) do |key, oldval, newval|
+            oldval.class == self.class ? oldval.rmerge!(newval) : newval
+        end
+      end
+
+      #
+      # Recursive version of Hash#merge
+      #
+      # Compared with Hash#merge!, this method supports nested hashes.
+      # When both +hsh+ and +other_hash+ contains an entry with the same key,
+      # it merges and returns the values from both arrays.
+      #
+      # Compared with Hash#merge, this method provides a different approch
+      # for merging nasted hashes.
+      # If the value of a given key is an Hash and both +other_hash+ abd +hsh
+      # includes the same key, the value is merged instead replaced with
+      # +other_hash+ value.
+      #
+      #    h1 = {"a" => 100, "b" => 200, "c" => {"c1" => 12, "c2" => 14}}
+      #    h2 = {"b" => 254, "c" => 300, "c" => {"c1" => 16, "c3" => 94}}
+      #    h1.rmerge(h2)    #=> {"a" => 100, "b" => 254, "c" => {"c1" => 16, "c2" => 14, "c3" => 94}}
+      #
+      # Simply using Hash#merge would return
+      #
+      #    h1.merge(h2)     #=> {"a" => 100, "b" = >254, "c" => {"c1" => 16, "c3" => 94}}
+      #
+      def rmerge(other_hash)
+        r = {}
+        merge(other_hash)  do |key, oldval, newval|
+          r[key] = oldval.class == self.class ? oldval.rmerge(newval) : newval
+        end
+      end
+    end
+
+    module ChainedQuerySupport
+      extend ActiveSupport::Concern
+
+      # returns a new relation, which is the result of filtering the current
+      # relation according to the conditions in the arguments if the given
+      # condition is met
+      def where?(condition, *args)
+        condition ? self.where(*args) : self
+      end
+    end
+
+    module BatchFinderSupport
+      extend ActiveSupport::Concern
+
+      # finds each record in batches while preserving
+      # the specified order of the relation
+      def find_each_with_order(options={})
+        return to_enum(__method__, options) unless block_given?
+        find_in_batches_with_order(options) do |records|
+          records.each { |record| yield record }
+        end
+      end
+
+      # finds each record in batches while preserving
+      # the specified order of the relation
+      # NOTE: any limit() on the query is overridden with the batch size
+      def find_in_batches_with_order(options={})
+        return to_enum(__method__, options) unless block_given?
+        options.assert_valid_keys(:batch_size)
+
+        relation = self
+
+        start = 0
+        batch_size = options.delete(:batch_size) || 1000
+
+        relation = relation.limit(batch_size)
+        records = relation.offset(start).to_a
+
+        while records.any?
+          records_size = records.size
+
+          yield records
+
+          break if records_size < batch_size
+
+          # get the next batch
+          start += batch_size
+          records = relation.offset(start + 1).to_a
+        end
+      end
+    end
+  end
+end
+
+# mixin extensions to respective classes
+
+class Object
+  include Riveter::CoreExtensions::BooleanSupport
+end
+
+class Date
+  include Riveter::CoreExtensions::DateExtensions
+end
+
+class Array
+  include Riveter::CoreExtensions::ArrayExtensions
+end
+
+class Hash
+  include Riveter::CoreExtensions::HashExtensions
+end
+
+class ActiveRecord::Relation
+  include Riveter::CoreExtensions::ChainedQuerySupport
+  include Riveter::CoreExtensions::BatchFinderSupport
+end
+
+module ActiveRecord
+  module Querying
+    delegate :find_each_with_order, :find_in_batches_with_order, :to => :scoped
+  end
+end

data/lib/riveter/email_validator.rb

@@ -0,0 +1,20 @@
+module Riveter
+  class EmailValidator < ActiveModel::EachValidator
+    def initialize(options)
+      @allow_nil, @allow_blank = options.delete(:allow_nil), options.delete(:allow_blank)
+      super
+    end
+
+    def validate_each(record, attribute, value)
+      return if (@allow_nil && value.nil?) || (@allow_blank && value.blank?)
+
+      unless value =~ /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\z/i
+        record.errors.add(attribute, :email, :value => value)
+      end
+    end
+  end
+end
+
+# add compatibility with ActiveModel validates method which
+# matches option keys to their validator class
+ActiveModel::Validations::EmailValidator = Riveter::EmailValidator

data/lib/riveter/enquiry.rb

@@ -0,0 +1,137 @@
+module Riveter
+  module Enquiry
+    extend ActiveSupport::Concern
+
+    included do
+      extend ActiveModel::Naming
+      extend ActiveModel::Translation
+
+      class << self
+        alias_method :enquiry_name, :model_name
+
+        def i18n_scope
+          :enquiries
+        end
+      end
+    end
+
+    module ClassMethods
+
+      def filter_with(query_filter_klass=nil, &block)
+        raise "Filter already defined." if self.respond_to?(:query_filter_class)
+
+        unless query_filter_klass
+          raise ArgumentError, "Missing block" unless block_given?
+
+          # define an anomymous class derived from QueryFilter
+          # which invokes the block given in the classes context
+          query_filter_klass = Class.new(QueryFilter::Base)
+          query_filter_klass.class_eval &block
+
+          # for anonymous classes, need to override the
+          # model_name method so that forms etc can work
+          enquiry_name = self.enquiry_name
+          query_filter_klass.class_eval do
+            define_singleton_method :model_name do
+              enquiry_name
+            end
+          end
+        end
+
+        define_singleton_method :query_filter_class do
+          query_filter_klass
+        end
+
+        define_method :query_filter_class do
+          query_filter_klass
+        end
+
+        define_singleton_method :query_filter_attributes do
+          query_filter_klass.attributes
+        end
+      end
+
+      def query_with(query_klass=nil, &block)
+        raise "Query already defined." if self.respond_to?(:query_class)
+
+        unless query_klass
+          raise ArgumentError, "Missing block" unless block_given?
+
+          # define an anomymous class derived from Query
+          # which delegates to the block given
+          query_klass = Class.new(Query::Base)
+          query_klass.class_eval do
+            define_method :build_relation, &block
+            protected :build_relation
+          end
+        end
+
+        define_singleton_method :query_class do
+          query_klass
+        end
+
+        define_method :query_class do
+          query_klass
+        end
+      end
+    end
+
+    def initialize
+      # sanity check
+      base_message = "#{self.class.name} enquiry not configured correctly."
+      raise "#{base_message} No query filter specified. Use the `filter_with` method to provide the query filter to use." unless self.class.respond_to?(:query_filter_class)
+      raise "#{base_message} No query specified. Use the `query_with` method to provide the query to use." unless self.class.respond_to?(:query_class)
+    end
+
+    def query_filter
+      @query_filter ||= query_filter_class.new()
+    end
+    alias_method :filter, :query_filter
+
+    def query_filter_attributes
+      query_filter_class.attributes
+    end
+
+    def submit(*args)
+      params = args.extract_options!
+
+      # filter and clean params before applying
+      @query_filter = create_query_filter(params)
+
+      # perform validations, and proceed if valid
+      return false unless @query_filter.valid?
+
+      # all good...
+      @query = create_query(@query_filter)
+    end
+
+    attr_reader :query
+
+    def find_each(&block)
+      self.query && self.query.find_each(&block)
+    end
+
+    def has_data?
+      self.query && self.query.has_data?
+    end
+
+    def query_results
+      self.query ? self.query.relation : nil
+    end
+
+  protected
+
+    def create_query_filter(params)
+      query_filter_class.new(params)
+    end
+
+    def create_query(query_filter)
+      query_class.new(query_filter)
+    end
+
+    # helper class
+    class Base
+      include Enquiry
+    end
+  end
+end

data/lib/riveter/enquiry_controller.rb

@@ -0,0 +1,80 @@
+module Riveter
+  module EnquiryController
+    extend ActiveSupport::Concern
+
+    # FIXME: provide ability to define more than one enquiry per controller
+
+    included do
+
+      class << self
+        #
+        # configures the controller for the given enquiry
+        #
+        # optionally define `on_success` and `on_failure` callback methods to
+        # provide additional controller logic as required
+        #
+        # options supported include:
+        #
+        #   :as               defines the name of the form used to access the params
+        #                     defaults to the name of the enquiry
+        #
+        #   :action           overrides the action name.
+        #                     by default is is ":index"
+        #
+        #   :attributes       the list of permitted attributes for initializing the enquiry instance
+        #                     defaults to the attributes defined using the `attr_*` helper methods
+        #
+        def enquiry_controller_for(enquiry_class, options={})
+          raise ArgumentError, "#{enquiry_class.name} does not include #{Enquiry.name} module or inherit from #{Enquiry::Base.name}" unless enquiry_class.ancestors.include?(Enquiry)
+
+          options = {
+            :as => enquiry_class.name.underscore.gsub(/_enquiry$/, ''),
+            :attributes => enquiry_class.query_filter_attributes,
+            :action => :index
+          }.merge(options)
+
+          action_method = options[:action]
+
+          # define instance methods
+          # which provide access to the given
+          # enquiry class and the options
+          define_method :enquiry_class do
+            enquiry_class
+          end
+
+          define_method :enquiry_options do
+            options
+          end
+
+          # define the 'index' action
+          class_eval <<-RUBY
+            def #{action_method}
+              @enquiry = enquiry_class.new()
+              if @enquiry.submit(enquiry_params)
+                on_success(@enquiry) if self.respond_to?(:on_success)
+              else
+                on_failure(@enquiry) if self.respond_to?(:on_failure)
+              end
+            end
+          RUBY
+
+          self.include ActionsAndSupport
+        end
+      end
+    end
+
+    module ActionsAndSupport
+      extend ActiveSupport::Concern
+
+      included do
+        # define the strong parameters method
+        def enquiry_params
+          params.key?(:reset) ? {} :
+            params.fetch(enquiry_options[:as], {})
+              .permit(*enquiry_options[:attributes])
+              .merge(:page => params.fetch(:page, 1))
+        end
+      end
+    end
+  end
+end