compendium 0.0.1 → 1.0.0

data/compendium.gemspec

@@ -10,12 +10,18 @@ Gem::Specification.new do |gem|
   gem.email         = ["dvandersluis@selfmgmt.com"]
   gem.description   = %q{Ruby on Rails reporting framework}
   gem.summary       = %q{Ruby on Rails reporting framework}
-  gem.homepage      = ""
+  gem.homepage      = "https://github.com/dvandersluis/compendium"
+  gem.license       = "MIT"
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
+  gem.add_dependency 'rails', '>= 3.0.0'
+  gem.add_dependency 'sass-rails', '>= 3.0.0'
+  gem.add_dependency 'compass-rails', '>= 1.0.0'
+  gem.add_dependency 'collection_of', '>= 1.0.3'
+  gem.add_dependency 'inheritable_attr', '>= 1.0.0'
   gem.add_development_dependency 'rspec', '~> 2.0'
 end

data/config/initializers/rails/active_record/connection_adapters/quoting.rb

@@ -0,0 +1,14 @@
+# ActiveRecord doesn't know how to handle SimpleDelegators when creating SQL
+# This means that when passing a SimpleDelegator (ie. Compendium::Param) into ActiveRecord::Base.find, it'll
+# crash.
+# Override AR::ConnectionAdapters::Quoting to forward a SimpleDelegator's object to be quoted.
+
+module ActiveRecord::ConnectionAdapters::Quoting
+  def quote_with_simple_delegator(value, column = nil)
+    return value.quoted_id if value.respond_to?(:quoted_id)
+    value = value.__getobj__ if value.is_a?(SimpleDelegator)
+    quote_without_simple_delegator(value, column)
+  end
+
+  alias_method_chain :quote, :simple_delegator
+end

data/config/initializers/ruby/numeric.rb

@@ -0,0 +1,26 @@
+# Monkey patch to determine if an object is numeric
+# Only Numerics and Strings/Symbols that are representations of numbers are numeric
+
+class Object
+  def numeric?
+    false
+  end
+end
+
+class String
+  def numeric?
+    !(self =~ /\A-?\d+(\.\d+)?\z|\A-?\.\d+\z/).nil?
+  end
+end
+
+class Symbol
+  def numeric?
+    to_s.numeric?
+  end
+end
+
+class Numeric
+  def numeric?
+    true
+  end
+end

data/config/locales/en.yml

@@ -0,0 +1,5 @@
+en:
+  compendium:
+    reports:
+      invalid_report: "Invalid report!"
+      generate_report: "Generate Report"

data/lib/compendium/abstract_chart_provider.rb

@@ -0,0 +1,30 @@
+require 'active_support/core_ext/string/inflections'
+
+module Compendium
+  # Abstract wrapper for rendering charts
+  # To add a new chart provider, #initialize and #render must be implemented
+  class AbstractChartProvider
+    attr_reader :chart
+
+    def initialize(type, data, &setup_proc)
+      raise NotImplementedError
+    end
+
+    def render(template, container)
+      raise NotImplementedError
+    end
+
+    # As more chart providers are added, this method will have to be extended to find them
+    def self.find_chart_provider
+      if defined?(AmCharts)
+        :AmCharts
+      else
+        self.name.demodulize.to_sym
+      end
+    end
+  end
+
+  module ChartProvider
+    autoload :AmCharts, 'compendium/chart_provider/amcharts'
+  end
+end

data/lib/compendium/chart_provider/amcharts.rb

@@ -0,0 +1,20 @@
+module Compendium
+  module ChartProvider
+    # Uses the amcharts.rb gem to provide charting
+    class AmCharts < Compendium::AbstractChartProvider
+      def initialize(type, data, &setup_proc)
+        @chart = chart_class(type).new(data, &setup_proc)
+      end
+
+      def render(template, container)
+        template.amchart(chart, container)
+      end
+
+    private
+
+      def chart_class(type)
+        ::AmCharts::Chart.const_get(type.to_s.titlecase)
+      end
+    end
+  end
+end

data/lib/compendium/context_wrapper.rb

@@ -0,0 +1,27 @@
+require 'delegate'
+
+module Compendium
+  class ContextWrapper
+    def self.wrap(ctx, parent, params = nil, &block)
+      delegator = ::SimpleDelegator.new(parent)
+
+      delegator.define_singleton_method(:__context__) { ctx }
+
+      delegator.instance_eval do
+        def method_missing(name, *args, &block)
+          return __context__.__send__(name, *args, &block) if __context__.respond_to?(name)
+          super
+        end
+
+        def respond_to_missing?(name, include_private = false)
+          return true if __context__.respond_to?(name, include_private)
+          super
+        end
+      end
+
+      return delegator.instance_exec(params, &block) if block_given?
+
+      delegator
+    end
+  end
+end

data/lib/compendium/dsl.rb

@@ -0,0 +1,79 @@
+require 'collection_of'
+require 'inheritable_attr'
+require 'compendium/option'
+require 'active_support/core_ext/class/attribute'
+
+module Compendium
+  module DSL
+    def self.extended(klass)
+      klass.inheritable_attr :queries, default: ::Collection[Query]
+      klass.inheritable_attr :options, default: {}
+    end
+
+    def query(name, opts = {}, &block)
+      define_query(name, opts, &block)
+    end
+    alias_method :chart, :query
+    alias_method :data, :query
+
+    def option(name, *args)
+      opts = args.extract_options!
+      type = args.shift
+
+      if options[name]
+        options[name].type = type if type
+        options[name].merge!(opts)
+      else
+        options[name] = Compendium::Option.new(opts.merge(name: name, type: type))
+      end
+    end
+
+    def metric(name, proc, opts = {})
+      raise ArgumentError, 'through option must be specified for metric' unless opts.key?(:through)
+
+      [opts.delete(:through)].flatten.each do |query|
+        raise ArgumentError, "query #{query} is not defined" unless queries.key?(query)
+        queries[query].add_metric(name, proc, opts)
+      end
+    end
+
+    # Allow defined queries to be redefined by name, eg:
+    # query :main_query
+    # main_query { collect_records_here }
+    def method_missing(name, *args, &block)
+      if queries.keys.include?(name.to_sym)
+        query = queries[name.to_sym]
+        query.proc = block if block_given?
+        query.options = args.extract_options!
+        return query
+      end
+
+      super
+    end
+
+    def respond_to_missing?(name, *args)
+      return true if queries.keys.include?(name)
+      super
+    end
+
+  private
+
+    def define_query(name, opts, type = Query, &block)
+      name = name.to_sym
+      query = type.new(name, opts, block)
+
+      if opts.key?(:through)
+        through = [opts[:through]].flatten
+
+        through.each do |q|
+          raise ArgumentError, "query #{q} is not defined" unless self.queries.include?(q.to_sym)
+        end
+
+        query.through = through
+      end
+
+      metrics[name] = opts[:metric] if opts.key?(:metric)
+      queries << query
+    end
+  end
+end

data/lib/compendium/engine/mount.rb

@@ -0,0 +1,13 @@
+module ActionDispatch
+  module Routing
+    class Mapper
+      def mount_compendium(options = {})
+        scope options[:at], controller: options.fetch(:controller, 'compendium/reports') do
+          get ':report_name', action: :setup, as: 'compendium_reports_setup'
+          post ':report_name', action: :run, as: 'compendium_reports_run'
+          root action: :index, as: 'compendium_reports_root'
+        end
+      end
+    end
+  end
+end

data/lib/compendium/engine.rb

@@ -0,0 +1,8 @@
+require 'compendium/engine/mount'
+
+module Compendium
+  if defined?(Rails)
+    class Engine < ::Rails::Engine
+    end
+  end
+end

data/lib/compendium/metric.rb

@@ -0,0 +1,29 @@
+module Compendium
+  Metric = Struct.new(:name, :query, :command, :options) do
+    attr_accessor :result
+
+    def initialize(*)
+      super
+      self.options ||= {}
+    end
+
+    def run(ctx, data)
+      self.result = if condition_failed?(ctx)
+        nil
+      else
+        command.is_a?(Symbol) ? ctx.send(command, data) : ctx.instance_exec(data, &command)
+      end
+    end
+
+    def ran?
+      !result.nil?
+    end
+    alias_method :has_ran?, :ran?
+
+  private
+
+    def condition_failed?(ctx)
+      (options.key?(:if) and !ctx.instance_exec(&options[:if])) or (options.key?(:unless) and ctx.instance_exec(&options[:unless]))
+    end
+  end
+end

data/lib/compendium/open_hash.rb

@@ -0,0 +1,68 @@
+require 'active_support/hash_with_indifferent_access'
+
+module Compendium
+  class OpenHash < ::ActiveSupport::HashWithIndifferentAccess
+    class << self
+      def [](hash = {})
+        new(hash)
+      end
+    end
+
+    def dup
+      self.class.new(self)
+    end
+
+  protected
+
+    def convert_value(value)
+      if value.is_a? Hash
+        Params[value].tap do |oh|
+          oh.each do |k, v|
+            oh[k] = convert_value(v) if v.is_a? Hash
+          end
+        end
+      elsif value.is_a?(Array)
+        value.dup.replace(value.map { |e| convert_value(e) })
+      else
+        value
+      end
+    end
+
+    def method_missing(name, *args, &block)
+      method = name.to_s
+
+      case method
+        when %r{.=$}
+          super unless args.length == 1
+          return self[method[0...-1]] = args.first
+
+        when %r{.\?$}
+          super unless args.empty?
+          return self.key?(method[0...-1].to_sym)
+
+        when %r{^_.}
+          super unless args.empty?
+          return self[method[1..-1]] if self.key?(method[1..-1].to_sym)
+
+        else
+          return self[method] if key?(method) or !respond_to?(method)
+      end
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      method = name.to_s
+
+      case method
+        when %r{.[=?]$}
+          return true if self.key?(method[0...-1])
+
+        when %r{^_.}
+          return true if self.key?(method[1..-1])
+      end
+
+      super
+    end
+  end
+end

data/lib/compendium/option.rb

@@ -0,0 +1,37 @@
+require 'compendium/open_hash'
+require 'active_support/string_inquirer'
+require 'active_support/core_ext/hash/indifferent_access'
+require 'active_support/core_ext/module/delegation'
+
+module Compendium
+  class Option
+    attr_reader :name, :type, :default, :options
+
+    delegate :boolean?, :date?, :dropdown?, :radio?, :text?, to: :type
+    delegate :merge, :merge!, :[], to: :@options
+
+    def initialize(hash = {})
+      raise ArgumentError, "name must be provided" unless hash.key?(:name)
+
+      @name = hash.delete(:name).to_sym
+      @default = hash.delete(:default)
+      self.type = hash.delete(:type)
+      @options = hash.with_indifferent_access
+    end
+
+    def type=(type)
+      @type = ActiveSupport::StringInquirer.new(type.to_s)
+    end
+
+    def method_missing(name, *args, &block)
+      return options[name] if options.key?(name)
+      return options.key?(name[0...-1]) if name.to_s.end_with?('?')
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      return true if options.key?(name)
+      super
+    end
+  end
+end

data/lib/compendium/param_types.rb

@@ -0,0 +1,91 @@
+require_relative '../../config/initializers/ruby/numeric'
+require 'delegate'
+
+module Compendium
+  class Param < ::SimpleDelegator
+    def boolean?; false; end
+    def date?; false; end
+    def dropdown?; false; end
+    def radio?; false; end
+
+    def ==(other)
+      return true if (value == other rescue false)
+      super
+    end
+
+    # Need to explicitly delegate nil? to the object, otherwise it's always false
+    # This is because SimpleDelegator is a non-nil object, and it only forwards non-defined methods!
+    def nil?
+      __getobj__.nil?
+    end
+  end
+
+  class ParamWithChoices < Param
+    def initialize(obj, choices)
+      @choices = choices
+
+      if @choices.respond_to?(:call)
+        # If given a proc, defer determining values until later.
+        index = obj
+      else
+        index = obj.numeric? ? obj.to_i : @choices.index(obj)
+        raise IndexError if (!obj.nil? and index.nil?) or index.to_i.abs > @choices.length - 1
+      end
+
+      super(index || 0)
+    end
+
+    def value
+      @choices[self]
+    end
+  end
+
+  class BooleanParam < Param
+    def initialize(obj, *)
+      # If given 0, 1, or a version thereof (ie. "0"), pass it along
+      return super obj.to_i if obj.numeric? and (0..1).cover?(obj.to_i)
+      super !!obj ? 0 : 1
+    end
+
+    def boolean?
+      true
+    end
+
+    def value
+      [true, false][self]
+    end
+
+    # When negating a BooleanParam, use the value instead
+    def !
+      !value
+    end
+  end
+
+  class DateParam < Param
+    def initialize(obj, *)
+      if obj.respond_to?(:to_date)
+        obj = obj.to_date
+      else
+        obj = Date.parse(obj) rescue nil
+      end
+
+      super obj
+    end
+
+    def date?
+      true
+    end
+  end
+
+  class RadioParam < ParamWithChoices
+    def radio?
+      true
+    end
+  end
+
+  class DropdownParam < ParamWithChoices
+    def dropdown?
+      true
+    end
+  end
+end

data/lib/compendium/params.rb

@@ -0,0 +1,40 @@
+require 'compendium/open_hash'
+require 'compendium/param_types'
+require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/object/blank'
+
+module Compendium
+  class Params < OpenHash
+    attr_reader :options
+
+    def initialize(hash = {}, options = {})
+      @options = options
+      super(prepare_hash_from_options(hash))
+    end
+
+  protected
+
+    def prepare_hash_from_options(params)
+      params = params.slice(*options.keys)
+
+      options.each do |option_name, metadata|
+        begin
+          klass = "Compendium::#{"#{metadata.type}Param".classify}".constantize
+          params[option_name] = klass.new(get_default_value(params[option_name], metadata.default), metadata[:choices])
+        rescue IndexError
+          raise IndexError, "invalid index for #{option_name}"
+        end
+      end
+
+      params
+    end
+
+    def get_default_value(current, default)
+      if current.blank? and !default.blank?
+        default.respond_to?(:call) ? default.call : default
+      else
+        current
+      end
+    end
+  end
+end

data/lib/compendium/query.rb

@@ -0,0 +1,94 @@
+require 'compendium/result_set'
+require 'compendium/params'
+require 'collection_of'
+
+module Compendium
+  class Query
+    attr_reader :name, :results, :metrics
+    attr_accessor :options, :proc, :through, :report
+
+    def initialize(name, options, proc)
+      @name = name
+      @options = options
+      @proc = proc
+      @metrics = ::Collection[Metric]
+    end
+
+    def initialize_clone(*)
+      super
+      @metrics = @metrics.clone
+    end
+
+    def run(params, context = self)
+      collect_results(params, context)
+      collect_metrics(context)
+
+      @results
+    end
+
+    def add_metric(name, proc, options = {})
+      Compendium::Metric.new(name, self.name, proc, options).tap { |m| @metrics << m }
+    end
+
+    def render_table(template, *options, &block)
+      Compendium::Presenters::Table.new(template, self, *options, &block).render
+    end
+
+    def render_chart(template, *options, &block)
+      Compendium::Presenters::Chart.new(template, self, *options, &block).render
+    end
+
+    def ran?
+      !@results.nil?
+    end
+    alias_method :has_run?, :ran?
+
+    def nil?
+      proc.nil?
+    end
+
+  private
+
+    def collect_results(params, context)
+      args = if through.nil?
+        params
+      else
+        collect_through_query_results(through, params, context)
+      end
+
+      command = context.instance_exec(args, &proc) if proc
+      command = fetch_results(command)
+      @results = ResultSet.new(command) if command
+    end
+
+    def collect_metrics(context)
+      metrics.each{ |m| m.run(context, results) } unless results.empty?
+    end
+
+    def fetch_results(command)
+      if options.key?(:through) or options.fetch(:collect, nil) == :active_record
+        command
+      else
+        ::ActiveRecord::Base.connection.select_all(command.respond_to?(:to_sql) ? command.to_sql : command)
+      end
+    end
+
+    def collect_through_query_results(through, params, context)
+      results = {}
+
+      through = [through].flatten.map(&method(:get_through_query))
+
+      through.each do |q|
+        q.run(params, context) unless q.ran?
+        results[q.name] = q.results.records
+      end
+
+      results = results[through.first.name] if through.size == 1
+      results
+    end
+
+    def get_through_query(name)
+      report.queries[name]
+    end
+  end
+end

data/lib/compendium/report.rb

@@ -0,0 +1,56 @@
+require 'active_support/core_ext/class/attribute_accessors'
+require 'active_support/core_ext/hash/slice'
+require 'compendium/dsl'
+
+module Compendium
+  class Report
+    attr_accessor :params, :results
+
+    extend Compendium::DSL
+
+    def self.inherited(report)
+      Compendium.reports << report
+    end
+
+    def initialize(params = {})
+      @params = Params.new(params, options)
+
+      # When creating a new report, map each query back to the report
+      queries.each { |q| q.report = self }
+    end
+
+    def run(context = nil)
+      self.context = context
+      self.results = {}
+
+      queries.each{ |q| self.results[q.name] = q.run(params, ContextWrapper.wrap(context, self)) }
+
+      self
+    end
+
+    def metrics
+      Collection[Metric, queries.map{ |q| q.metrics.to_a }.flatten]
+    end
+
+  private
+
+    attr_accessor :context
+
+    def method_missing(name, *args, &block)
+      prefix = name.to_s.sub(/(?:_results|\?)\Z/, '').to_sym
+
+      return queries[name] if queries.keys.include?(name)
+      return results[prefix] if name.to_s.end_with? '_results' and queries.keys.include?(prefix)
+      return params[name] if options.keys.include?(name)
+      return !!params[prefix] if name.to_s.end_with? '?' and options.keys.include?(prefix)
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      prefix = name.to_s.sub(/_results\Z/, '').to_sym
+      return true if queries.keys.include?(name)
+      return true if name.to_s.end_with? '_results' and queries.keys.include?(prefix)
+      super
+    end
+  end
+end

data/lib/compendium/result_set.rb

@@ -0,0 +1,24 @@
+require 'active_support/core_ext/module/delegation'
+
+module Compendium
+  class ResultSet
+    delegate :first, :last, :to_a, :empty?, :each, :map, :[], :count, :length, :size, :==, to: :records
+
+    attr_reader :records
+    alias :all :records
+
+    def initialize(records)
+      @records = records.map do |r|
+        r.respond_to?(:with_indifferent_access) ? r.with_indifferent_access : r
+      end
+    end
+
+    def keys
+      records.is_a?(Array) ? first.keys : records.keys
+    end
+
+    def as_json(options = {})
+      records.map{ |r| r.except(*options[:except]) }
+    end
+  end
+end