mochigome 0.0.2

data/README.rdoc

@@ -0,0 +1,11 @@
+*NOTE*: This gem is a work in progress.
+
+*NOTE*: Currently the gem is only compatible with Rails 2.
+
+== Overview
+
+Mochigome builds sophisticated report datasets from your ActiveRecord models.
+
+== Why "Mochigome"?
+
+It means "sticky rice", a kind of rice where the grains tend to clump together. The Mochigome gem makes a bunch of ActiveRecord models clump together to form a single comprehensive report.

data/Rakefile

@@ -0,0 +1,74 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rdoc/task'
+require 'rubygems/package_task'
+require 'rcov/rcovtask'
+require 'ruby-prof/task'
+
+require 'bundler/setup'
+Bundler.require(:default)
+
+def common_test_settings(t)
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Default: run unit and functional tests.'
+task :default => :test
+
+desc 'Test Mochigome'
+Rake::TestTask.new(:test) do |t|
+  common_test_settings(t)
+end
+
+desc 'Run tests automatically as files change'
+task :watchr do |t|
+  exec 'watchr test/test.watchr'
+end
+
+desc 'Generate documentation for Mochigome.'
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Mochigome'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Rcov::RcovTask.new(:rcov) do |t|
+  common_test_settings(t)
+  t.pattern = 'test/unit/*_test.rb' # Don't care about coverage added by functional tests
+  t.rcov_opts << '-o coverage -x "/ruby/,/gems/,/test/,/migrate/"'
+end
+  
+RubyProf::ProfileTask.new(:profile) do |t|
+  common_test_settings(t)
+  t.output_dir = "#{File.dirname(__FILE__)}/profile"
+  t.printer = :call_tree
+  t.min_percent = 10
+end
+
+require 'lib/mochigome_ver'
+gemspec = Gem::Specification.new do |s|
+  s.name         = "mochigome"
+  s.version      = Mochigome::VERSION
+  s.authors      = ["David Mike Simon"]
+  s.email        = "david.mike.simon@gmail.com"
+  s.homepage     = "http://github.com/DavidMikeSimon/mochigome"
+  s.summary      = "User-customizable report generator"
+  s.description  = "Mochigome builds sophisticated report datasets from your ActiveRecord models"
+  s.files        = `git ls-files .`.split("\n") - [".gitignore"]
+  s.platform     = Gem::Platform::RUBY
+  s.require_path = 'lib'
+  s.rubyforge_project = '[none]'
+
+  s.add_dependency('ruport')
+  s.add_dependency('nokogiri')
+  s.add_dependency('rgl')
+end
+
+Gem::PackageTask.new(gemspec) do |pkg|
+end

data/TODO

@@ -0,0 +1,6 @@
+- Still need some way to filter queries by weird stuff (i.e. EffectivelyDatedAssociation, or to filter AttendanceRecords by the dates on the Sessions that they belong_to)
+  - Maybe can do this by adjusting the EffectivelyDated module so that when included it calls a hook on Mochigome that describes the possible filter on the effectively dated object (i.e. SectionRoster) as an SQL snippet referencing "SectionRoster" typed entries of the effective dates table.
+- Do as few queries as possible to accomplish stuff; this also encourages app to rely on SQL's 'IN' syntax and magical grouping/joining abilities to make aggregation easier
+- Replace all the TODOs and FIXMEs with whatever they're asking for (additional checks, use of ordered indifferent hashes instead of arrays of hashes, etc.)
+- If there is more than one association from model A to model B and they're both focusable, pick the one with no conditions. If all the associations have conditions, complain and require that the correct association be manually specified (where "correct" might mean none of them should be valid)
+  - Alternately, always ignore conditional associations unless they're specifically provided to Mochigome by the model

data/lib/data_node.rb

@@ -0,0 +1,106 @@
+require 'active_support'
+
+module Mochigome
+  class DataNode < ActiveSupport::OrderedHash
+    attr_accessor :type_name
+    attr_accessor :name
+    attr_accessor :comment
+    attr_reader :children
+
+    def initialize(type_name, name, content = [])
+      # Convert content keys to symbols
+      super()
+      self.merge!(content)
+      @type_name = type_name.to_s
+      @name = name.to_s
+      @comment = nil
+      @children = []
+    end
+
+    def merge!(a)
+      if a.is_a?(Array)
+        a.each do |h|
+          self[h.keys.first.to_sym] = h.values.first
+        end
+      else
+        super
+      end
+    end
+
+    def <<(item)
+      if item.is_a?(Array)
+        item.map {|i| self << i}
+      else
+        raise DataNodeError.new("New child #{item} is not a DataNode") unless item.is_a?(DataNode)
+        @children << item
+        @children.last
+      end
+    end
+
+    # TODO: Only define xml-related methods if nokogiri loaded
+    def to_xml
+      doc = Nokogiri::XML::Document.new
+      append_xml_to(doc)
+      doc
+    end
+
+    # TODO: Only define ruport-related methods if ruport is loaded
+    def to_flat_ruport_table
+      col_names = flat_column_names
+      table = Ruport::Data::Table.new(:column_names => col_names)
+      append_rows_to(table, col_names.size)
+      table
+    end
+
+    def to_flat_arrays
+      table = []
+      col_names = flat_column_names
+      table << col_names
+      append_rows_to(table, col_names.size)
+      table
+    end
+
+    private
+
+    def append_xml_to(x)
+      doc = x.document
+      node = Nokogiri::XML::Node.new("node", doc)
+      node["type"] = @type_name.titleize
+      node["name"] = @name
+      [:id, :internal_type].each do |attr|
+        node[attr.to_s] = delete(attr).to_s if has_key?(attr)
+      end
+      node.add_child(Nokogiri::XML::Comment.new(doc, @comment)) if @comment
+      each do |key, value|
+        sub_node = Nokogiri::XML::Node.new("datum", doc)
+        sub_node["name"] = key.to_s.titleize
+        sub_node.content = value
+        node.add_child(sub_node)
+      end
+      @children.each do |child|
+        child.send(:append_xml_to, node)
+      end
+      x.add_child(node)
+    end
+
+    # TODO: Should handle trickier situations involving datanodes not having various columns
+    def flat_column_names
+      colnames = (["name"] + keys).map {|key| "#{@type_name}::#{key}"}
+      choices = @children.map(&:flat_column_names)
+      colnames += choices.max_by(&:size) || []
+      colnames
+    end
+
+    # TODO: Should handle trickier situations involving datanodes not having various columns
+    def append_rows_to(table, pad, stack = [])
+      stack.push([@name] + values)
+      if @children.size > 0
+        @children.each {|child| child.send(:append_rows_to, table, pad, stack)}
+      else
+        row = stack.flatten(1)
+        table << (row + Array.new(pad - row.size, nil))
+      end
+      stack.pop
+    end
+  end
+end

data/lib/exceptions.rb

@@ -0,0 +1,6 @@
+module Mochigome
+  class ModelSetupError < StandardError; end
+  class InvalidLayerError < StandardError; end
+  class QueryError < StandardError; end
+  class DataNodeError < StandardError; end
+end

data/lib/mochigome.rb

@@ -0,0 +1,7 @@
+require 'mochigome_ver'
+require 'exceptions'
+require 'data_node'
+require 'query'
+require 'model_extensions'
+
+ActiveRecord::Base.send(:include, Mochigome::ModelExtensions)

data/lib/mochigome_ver.rb

@@ -0,0 +1,3 @@
+module Mochigome
+  VERSION = "0.0.2"
+end

data/lib/model_extensions.rb

@@ -0,0 +1,211 @@
+module Mochigome
+  @reportFocusModels = []
+  def self.reportFocusModels
+    @reportFocusModels
+  end
+
+  module ModelExtensions
+    def self.included(base)
+      base.extend(ClassMethods)
+
+      base.write_inheritable_attribute :mochigome_focus_settings, nil
+      base.class_inheritable_reader :mochigome_focus_settings
+
+      base.write_inheritable_attribute :mochigome_aggregations, []
+      base.class_inheritable_reader :mochigome_aggregations
+    end
+
+    module ClassMethods
+      def acts_as_mochigome_focus
+        if self.try(:mochigome_focus_settings).try(:orig_class) == self
+          raise Mochigome::ModelSetupError.new("Already acts_as_mochigome_focus for #{self.name}")
+        end
+        settings = ReportFocusSettings.new(self)
+        yield settings if block_given?
+        write_inheritable_attribute :mochigome_focus_settings, settings
+        send(:include, InstanceMethods)
+        Mochigome::reportFocusModels << self
+      end
+
+      def acts_as_mochigome_focus?
+        !!mochigome_focus_settings
+      end
+
+      AGGREGATION_FUNCS = {
+        'count' => 'count()',
+        'distinct' => 'count(distinct %s)',
+        'average' => 'avg(%s)',
+        'avg' => 'avg(%s)',
+        'minimum' => 'min(%s)',
+        'min' => 'min(%s)',
+        'maximum' => 'max(%s)',
+        'max' => 'max(%s)',
+        'sum' => 'sum(%s)'
+      }
+
+      def has_mochigome_aggregations(aggregations)
+        unless aggregations.respond_to?(:each)
+          raise ModelSetupError.new "Call has_mochigome_aggregations with an Enumerable"
+        end
+
+        def aggregation_opts(obj)
+          if obj.is_a?(String) or obj.is_a?(Symbol)
+            obj = obj.to_s
+            AGGREGATION_FUNCS.each do |func, expr_pat|
+              if expr_pat.include?('%s')
+                if obj =~ /^#{func}[-_ ](.+)/i
+                  return {:expr => (expr_pat % $1)}
+                end
+              else
+                if obj.downcase == func
+                  return {:expr => expr_pat}
+                end
+              end
+            end
+            return {:expr => obj} # Assume the string is just a plain SQL expression
+          elsif obj.is_a?(Array) and obj.size == 2
+            return {:conditions => obj[1]}.merge(aggregation_opts(obj[0]))
+          end
+          raise ModelSetupError.new "Invalid aggregation expr: #{obj.inspect}"
+        end
+
+        additions = aggregations.map do |f|
+          case f
+          when String, Symbol then
+            {:name => "%s %s" % [name.pluralize, f.to_s.sub("_", " ")]}.merge(aggregation_opts(f))
+          when Hash then
+            {:name => f.keys.first.to_s}.merge(aggregation_opts(f.values.first))
+          else raise ModelSetupError.new "Invalid aggregation: #{f.inspect}"
+          end
+        end
+        mochigome_aggregations.concat(additions)
+      end
+    end
+
+    module InstanceMethods
+      def mochigome_focus
+        ReportFocus.new(self, self.class.mochigome_focus_settings)
+      end
+    end
+  end
+
+  private
+
+  class ReportFocus
+    attr_reader :type_name
+    attr_reader :fields
+
+    def initialize(owner, settings)
+      @owner = owner
+      @name_proc = settings.options[:name] || lambda{|obj| obj.name}
+      @type_name = settings.options[:type_name] || owner.class.name
+      @fields = settings.options[:fields] || []
+    end
+
+    def name
+      @name_proc.call(@owner)
+    end
+
+    def data(options = {})
+      field_data.merge(aggregate_data(:all, options))
+    end
+
+    def field_data
+      h = ActiveSupport::OrderedHash.new
+      self.fields.each do |field|
+        h[field[:name]] = field[:value_func].call(@owner)
+      end
+      h
+    end
+
+    def aggregate_data(assoc_name, options = {})
+      h = ActiveSupport::OrderedHash.new
+      assoc_name = assoc_name.to_sym
+      if assoc_name == :all
+        @owner.class.reflections.each do |name, assoc|
+          h.merge! aggregate_data(name, options)
+        end
+      else
+        assoc = @owner.class.reflections[assoc_name]
+        assoc_object = @owner
+        # TODO: Are there other ways context could matter besides :through assocs?
+        # TODO: What if a through reflection goes through _another_ through reflection?
+        if options.has_key?(:context) && assoc.through_reflection
+          # FIXME: This seems like it's repeating Query work
+          join_objs = assoc_object.send(assoc.through_reflection.name)
+          options[:context].each do |obj|
+            next unless join_objs.include?(obj)
+            assoc = assoc.source_reflection
+            assoc_object = obj
+            break
+          end
+        end
+        assoc.klass.mochigome_aggregations.each do |agg|
+          # TODO: There *must* be a better way to do this query
+          # It's ugly, involves an ActiveRecord creation, and causes lots of DB hits
+          sel_expr = "(#{agg[:expr]}) AS x"
+          cond_expr = agg[:conditions] ? agg[:conditions] : "1=1"
+          if assoc.belongs_to? # FIXME: or has_one
+            obj = assoc_object.send(assoc.name)
+            row = obj.class.find(obj.id, :select => sel_expr, :conditions => cond_expr)
+          else
+            row = assoc_object.send(assoc.name).first(:select => sel_expr, :conditions => cond_expr)
+          end
+          h[agg[:name]] = row.x
+        end
+      end
+      h
+    end
+  end
+
+  class ReportFocusSettings
+    attr_reader :options
+    attr_reader :orig_class
+
+    def initialize(orig_class)
+      @orig_class = orig_class
+      @options = {}
+      @options[:fields] = []
+    end
+
+    def type_name(n)
+      unless n.is_a?(String)
+        raise ModelSetupError.new "Call f.type_name with a String"
+      end
+      @options[:type_name] = n
+    end
+
+    def name(n)
+      @options[:name] = n.to_proc
+    end
+
+    def fields(fields)
+      def complain_if_reserved(s)
+        ['name', 'id', 'type', 'internal_type'].each do |reserved|
+          if s.gsub(/ +/, "_").underscore == reserved
+            raise ModelSetupError.new "Field name \"#{s}\" conflicts with reserved term \"#{reserved}\""
+          end
+        end
+        s
+      end
+
+      unless fields.respond_to?(:each)
+        raise ModelSetupError.new "Call f.fields with an Enumerable"
+      end
+
+      @options[:fields] += fields.map do |f|
+        case f
+        when String, Symbol then {
+          :name => complain_if_reserved(f.to_s.strip),
+          :value_func => lambda{|obj| obj.send(f.to_sym)}
+        }
+        when Hash then {
+          :name => complain_if_reserved(f.keys.first.to_s.strip),
+          :value_func => f.values.first.to_proc
+        }
+        else raise ModelSetupError.new "Invalid field: #{f.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/query.rb

@@ -0,0 +1,199 @@
+require 'rgl/adjacency'
+
+module Mochigome
+  class Query
+    def initialize(layer_types, name = "report")
+      # TODO: Validate layer types: not empty, AR, act_as_mochigome_focus, graph correctly, no repeats
+      @layer_types = layer_types
+      @name = name
+    end
+
+    def run(objs)
+      objs = [objs] unless objs.is_a?(Enumerable)
+      return DataNode.new(:report, @name) if objs.size == 0 # Empty DataNode for empty input
+
+      unless objs.all?{|obj| obj.class == objs.first.class}
+        raise QueryError.new("Query target objects must all be the same type")
+      end
+
+      unless @layer_types.any?{|layer| objs.first.is_a?(layer)}
+        raise QueryError.new("Query target object type must be in the query layer list")
+      end
+
+      # Used to provide debugging information in the root DataNode comment
+      assoc_path = ["== #{objs.first.class.name} =="]
+
+      # Start at the layer for objs, and descend downwards through layers after that
+      #TODO: It would be really fantastic if I could just use AR eager loading for this
+      downwards_layers = @layer_types.drop_while{|cls| !objs.first.is_a?(cls)}
+      root = DataNode.new(:report, @name)
+      root << objs.map{|obj| DataNode.new(
+        obj.mochigome_focus.type_name,
+        obj.mochigome_focus.name,
+        [{:obj => obj}]
+      )}
+      cur_layer = root.children
+      downwards_layers.drop(1).each do |cls|
+        new_layer = []
+        assoc = Query.edge_assoc(cur_layer.first[:obj].class, cls)
+
+        assoc_str = "-> #{cls.name} via #{cur_layer.first[:obj].class.name}##{assoc.name}"
+        if assoc.through_reflection
+          assoc_str << " (thru #{assoc.through_reflection.name})"
+        end
+        assoc_path.push assoc_str
+
+        cur_layer.each do |datanode|
+          # FIXME: Don't assume that downwards means plural association
+          # TODO: Are there other ways context could matter besides :through assocs?
+          # i.e. If C belongs_to A and also belongs_to B, and layer_types = [A,B,C]
+          # TODO: What if a through reflection goes through _another_ through reflection?
+          if assoc.through_reflection
+            datanode[:obj].send(assoc.through_reflection.name).each do |through_obj|
+              # TODO: Don't assume that through means singular!
+              obj = through_obj.send(assoc.source_reflection.name)
+              subnode = datanode << DataNode.new(
+                obj.mochigome_focus.type_name,
+                obj.mochigome_focus.name,
+                {:obj => obj, :through_obj => through_obj}
+              )
+              new_layer << subnode
+            end
+          else
+            #FIXME: Not DRY
+            datanode[:obj].send(assoc.name).each do |obj|
+              subnode = datanode << DataNode.new(
+                obj.mochigome_focus.type_name,
+                obj.mochigome_focus.name,
+                [{:obj => obj}]
+              )
+              new_layer << subnode
+            end
+          end
+        end
+        cur_layer = new_layer
+      end
+
+      # Take our tree so far and include it in parent trees, going up to the first layer
+      upwards_layers = @layer_types.take_while{|cls| !objs.first.is_a?(cls)}.reverse
+      upwards_layers.each do |cls|
+        assoc = Query.edge_assoc(root.children.first[:obj].class, cls)
+
+        assoc_str =  "<- #{cls.name} via #{root.children.first[:obj].class.name}##{assoc.name}"
+        if assoc.through_reflection
+          assoc_str << " (thru #{assoc.through_reflection.name})"
+        end
+        assoc_path.unshift assoc_str
+
+        parent_children_map = ActiveSupport::OrderedHash.new
+        root.children.each do |child|
+          if assoc.through_reflection
+            through_objs = child[:obj].send(assoc.through_reflection.name)
+            through_objs = [through_objs] unless through_objs.is_a?(Enumerable)
+            through_objs.each do |through_obj|
+              # TODO: Don't assume that through means singular!
+              parent = through_obj.send(assoc.source_reflection.name)
+              unless parent_children_map.has_key?(parent.id)
+                attrs = {:obj => parent, :through_obj => through_obj}
+                parent_children_map[parent.id] = DataNode.new(
+                  parent.mochigome_focus.type_name,
+                  parent.mochigome_focus.name,
+                  attrs
+                )
+              end
+              parent_children_map[parent.id] << child.dup
+            end
+          else
+            #FIXME: Not DRY
+            parents = child[:obj].send(assoc.name)
+            parents = [parents] unless parents.is_a?(Enumerable)
+            parents.each do |parent|
+              unless parent_children_map.has_key?(parent.id)
+                attrs = {:obj => parent}
+                parent_children_map[parent.id] = DataNode.new(
+                  parent.mochigome_focus.name,
+                  parent.mochigome_focus.type_name,
+                  attrs
+                )
+              end
+              parent_children_map[parent.id] << child.dup
+            end
+          end
+        end
+
+        root = DataNode.new(:report, @name)
+        root << parent_children_map.values
+      end
+
+      root.comment = <<-eos
+        Mochigome Version: #{Mochigome::VERSION}
+        Time: #{Time.now}
+        Layers: #{@layer_types.map(&:name).join(" => ")}
+        AR Association Path:
+        #{assoc_path.map{|s| "* #{s}"}.join("\n")}
+      eos
+      root.comment.gsub!(/\n +/, "\n")
+      root.comment.lstrip!
+
+      focus_data_node_objs(root)
+      return root
+    end
+
+    private
+
+    def focus_data_node_objs(node, obj_stack=[], commenting=true)
+      pushed = 0
+      if node.has_key?(:obj)
+        obj = node.delete(:obj)
+        if node.has_key?(:through_obj)
+          obj_stack.push(node.delete(:through_obj)); pushed += 1
+        end
+        obj_stack.push(obj); pushed += 1
+        if commenting
+          node.comment = <<-eos
+            Context:
+            #{obj_stack.map{|o| "#{o.class.name}:#{o.id}"}.join("\n")}
+          eos
+          node.comment.gsub!(/\n +/, "\n")
+          node.comment.lstrip!
+        end
+        node.merge!(obj.mochigome_focus.data(:context => obj_stack))
+        node[:internal_type] = obj.class.name
+      end
+      node.children.each_index do |i|
+        focus_data_node_objs(node.children[i], obj_stack, i == 0 && commenting)
+      end
+      pushed.times{ obj_stack.pop }
+    end
+
+    @@assoc_graph = nil
+    @@edge_assocs = {}
+
+    def self.assoc_graph
+      return @@assoc_graph if @assoc_graph
+
+      # Build a directed graph of the associations between focusable models
+      @@assoc_graph = RGL::DirectedAdjacencyGraph.new
+      @@assoc_graph.add_vertices(*Mochigome::reportFocusModels)
+      Mochigome::reportFocusModels.each do |cls|
+        # Add any associations that lead to other reportFocusModels
+        cls.reflections.each do |name, assoc|
+          if Mochigome::reportFocusModels.include?(assoc.klass)
+            @@assoc_graph.add_edge(cls, assoc.klass)
+            @@edge_assocs[[cls, assoc.klass]] = assoc
+          end
+        end
+      end
+      return @@assoc_graph
+    end
+
+    def self.edge_assoc(u, v)
+      assoc_graph # Make sure @@edge_assocs has been populated
+      assoc = @@edge_assocs[[u,v]]
+      unless assoc
+        raise QueryError.new("No association between #{u} and #{v}")
+      end
+      return assoc
+    end
+  end
+end

data/test/app_root/app/controllers/application_controller.rb

@@ -0,0 +1,2 @@
+class ApplicationController < ActionController::Base
+end

data/test/app_root/app/controllers/owners_controller.rb

@@ -0,0 +1,2 @@
+class OwnersController < ApplicationController
+end

data/test/app_root/app/models/boring_datum.rb

@@ -0,0 +1,3 @@
+class BoringDatum < ActiveRecord::Base
+  # Does not act as report focus
+end

data/test/app_root/app/models/category.rb

@@ -0,0 +1,7 @@
+class Category < ActiveRecord::Base
+  acts_as_mochigome_focus
+
+  has_many :products, :conditions => {:categorized => true}
+
+  validates_presence_of :name
+end

data/test/app_root/app/models/owner.rb

@@ -0,0 +1,17 @@
+class Owner < ActiveRecord::Base
+  acts_as_mochigome_focus
+
+  has_many :stores
+
+  def name(reverse = false)
+    if reverse
+      "#{last_name}, #{first_name}"
+    else
+      "#{first_name} #{last_name}"
+    end
+  end
+
+  def age
+    ((Date.today - birth_date)/365.25).floor
+  end
+end

data/test/app_root/app/models/product.rb

@@ -0,0 +1,21 @@
+class Product < ActiveRecord::Base
+  acts_as_mochigome_focus do |f|
+    f.fields [:price]
+  end
+  has_mochigome_aggregations [
+    :average_price,
+    {"Power level" => "9000+1"},
+    {"Expensive products" => [:count, "price > 40"]}
+  ]
+
+  belongs_to :category
+  has_many :store_products
+  has_many :stores, :through => :store_products
+  has_many :sales, :through => :store_products
+
+  validates_presence_of :name
+  validates_presence_of :price
+  validates_numericality_of :price, :greater_than_or_equal_to => 0
+  # Note: Does NOT validate presence of category!
+  # We want to be able to find category-less products with a report.
+end