calculon 0.0.1 → 0.0.2

data/README.md

@@ -29,7 +29,7 @@ Let's say you have a Game model with two columns, one for Team A's points and th
 
 ```ruby
 class Game
-    attr_accessible :team_a_points, :team_b_points
+  attr_accessible :team_a_points, :team_b_points
 end
 ```
 
@@ -39,7 +39,9 @@ And now you want to know the total points for both teams by day:
 Game.by_day(:team_a_points => :sum, :team_b_points => :sum)
 ```
 
-Awesome.  Now let's say you want to know the average yesterday where Team A scored more than 0 points:
+This will return an array of Game instances where team_a_points and team_b_points are the sums per hour (the attribute time_bucket will give you the name of each bucket).
+
+Now let's say you want to know the average yesterday where Team A scored more than 0 points:
 
 ```ruby
 Game.by_day(:team_a_points => :avg, :team_b_points => :avg).on(Date.yesterday).where('team_a_points > 0')
@@ -49,7 +51,7 @@ Now say you hate typing, and want to get points more easily:
 
 ```ruby
 class Game
-    calculon_view :points, :team_a_points => :sum, :team_b_points => :sum
+  calculon_view :points, :team_a_points => :sum, :team_b_points => :sum
 end
 ```
 
@@ -64,8 +66,43 @@ Game.points_by_year
 Let's say, however, that you want to know points by hour, but you want to get 24 results, regardless of whether or not a team scored (i.e., you want to fill in the "missing" hours):
 
 ```ruby
+# first, get the buckets out
+buckets = Game.points_by_hour.on(Date.yesterday).to_buckets
+
+# then, convert to array with filled values
 nogame = OpenStruct.new(:team_a_points => 0, :team_b_points => 0)
-Game.points_by_hour.on(Date.yesterday).to_filled_a(nogame)
+buckets.to_a(nogame)
 ```
 
 This will return an array of length 24, with "nogame" filling in each hour for which there was no game.
+
+### Multiple Grouping Columns
+If you want to be able to group by other columns per time period, you can do that as well.
+
+```ruby
+# the :group_by option takes either a single additional column or an array of columns
+buckets = Game.points_by_hour(:group_by => :bracket_id).on(Date.yesterday).to_buckets
+
+# see all of the unique grouping values
+buckets.groupings
+#=> { :bracket_id => 1, :bracket_id => 2 }
+
+# get all of the time values for just bracket_id 1.  Since this was by day, there will
+# be 24 of them
+buckets.values_for(:bracket_id => 1)
+#=> [ #<Game ...>, #<Game ...>, ... ]
+
+buckets.values_for(:bracket_id => 2)
+#=> [ #<Game ...>, #<Game ...>, ... ]
+
+# now, try one that doesn't exist
+buckets.values_for(:bracket_id => 100)
+#=> [ nil, nil, ... ]
+
+# now, try one that doesn't exist, but w/ default value
+buckets.values_for({:bracket_id => 100}, OpenStruct.new(:points => 0))
+#=> [ #<OpenStruct points=0>, #<OpenStruct points=0>, ... ]
+```
+
+## Supported Databases
+Right now, mysql2 is the only supported DB interface supported.

data/Rakefile

@@ -1,6 +1,10 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
 require 'bundler/gem_tasks'
 require 'rake/testtask'
-require 'rdoc/task'
+require 'yard'
+require 'calculon/version'
 
 Rake::TestTask.new("test") { |t|
   t.libs += ["lib", "."]
@@ -10,9 +14,7 @@ Rake::TestTask.new("test") { |t|
 
 task :default => [:test]
 
-RDoc::Task.new("doc") { |rdoc|
-  rdoc.title = "Calculon - aggregate methods for models for Rails"
-  rdoc.rdoc_dir = 'docs'
-  rdoc.rdoc_files.include('README.md')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-}
+YARD::Rake::YardocTask.new(:doc) do |task|
+  task.files  = FileList["lib/**/*.rb"]
+  task.options = "--output", "docs", "--title", "Calculon #{Calculon::VERSION}", "--main", "README.md"
+end

data/calculon.gemspec

@@ -16,7 +16,8 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
   gem.add_dependency("rails", ">= 3.2.0")
-  gem.add_development_dependency('rdoc')
+  gem.add_development_dependency('yard')
+  gem.add_development_dependency('redcarpet')
   gem.add_development_dependency('rake')
   gem.add_development_dependency('sqlite3')
   gem.add_development_dependency('mysql2')

data/lib/calculon.rb

@@ -1,25 +1,7 @@
 require "calculon/version"
 require 'calculon/railtie'
-require 'calculon/summarized_results'
-
-module ActiveRecord
-  module QueryMethods
-    attr_accessor :calculon_opts
-  end
-
-  class Relation
-    def to_results_hash
-      if(calculon_opts.nil?)
-        raise "Not a Calculon Relation: You must call by_day/by_hour/etc before you can call to_hash"
-      end
-      Calculon::SummarizedResults.new(self)
-    end
-
-    def to_filled_a(default=nil)
-      to_results_hash.fill_missing!(default).to_a
-    end
-  end
-end
+require 'calculon/results'
+require 'calculon/ext'
 
 module Calculon
   def self.included(base)
@@ -33,7 +15,8 @@ module Calculon
         [ "minute", "hour", "day", "month", "year" ].each do |window|
           define_method("#{name}_by_#{window}") { |nopts=nil|
             nopts = (opts || {}).merge(nopts || {})
-            send("by_#{window}".intern, cols, nopts)
+            # clone cols so modifications downstream don't affect our original copy here
+            send("by_#{window}".intern, cols.clone, nopts)
           }
         end
       end
@@ -45,7 +28,7 @@ module Calculon
 
     def default_calculon_opts
       @@calculon_time_column ||= "created_at"
-      { :time_column => @@calculon_time_column, :bycols => [] }
+      { :time_column => @@calculon_time_column, :group_by => [] }
     end
 
     def on(date, opts=nil)
@@ -85,6 +68,8 @@ module Calculon
 
     def by_bucket(bucket_name, bucket, cols, opts=nil)
       opts = default_calculon_opts.merge(opts || {})
+      # allow group by to be either single symbol or array of symbols
+      opts[:group_by] = [opts[:group_by]].flatten
 
       unless ActiveRecord::Base.connection.adapter_name == "Mysql2"
         raise "Mysql2 is the only supported connection adapter for calculon"
@@ -98,8 +83,8 @@ module Calculon
       bucket = bucket % { :time_column => time_column }
 
       # if we're grouping by other columns, we need to select them
-      groupby = opts[:bycols] + ["time_bucket"]
-      opts[:bycols].each { |c| cols[c] = nil }
+      groupby = opts[:group_by] + ["time_bucket"]
+      opts[:group_by].each { |c| cols[c] = nil }
       cols = cols.map { |name,method| 
         asname = name.to_s.gsub(' ', '').tr('^A-Za-z0-9', '_')
         method.nil? ? name : "#{method}(#{name}) as #{asname}" 

data/lib/calculon/ext.rb

@@ -0,0 +1,14 @@
+module ActiveRecord
+  module QueryMethods
+    attr_accessor :calculon_opts
+  end
+
+  class Relation
+    def to_buckets
+      if(calculon_opts.nil?)
+        raise "Not a Calculon Relation: You must call by_day/by_hour/etc before you can call to_buckets"
+      end
+      Calculon::Results.create(self)
+    end
+  end
+end

data/lib/calculon/{summarized_results.rb → results.rb}

@@ -1,12 +1,15 @@
+require 'set'
+
 module Calculon
-  class SummarizedResults < Hash
+  class Results < Hash
     attr_reader :rows
 
     def initialize(relation)
       super({})
 
       @bucket_size = relation.calculon_opts[:bybucket]
-      @grouped_by = relation.calculon_opts[:bycols] || []
+      @grouped_by = relation.calculon_opts[:group_by] || []
+      @grouped_by_values = Set.new
 
       @start_time = relation.calculon_opts[:starttime] || keys.sort.first
       @start_time = @start_time.to_time if @start_time.is_a?(Date)
@@ -15,23 +18,22 @@ module Calculon
       @end_time = @end_time.to_time if @end_time.is_a?(Date)
 
       relation.to_a.each { |row|
-        self[row.time_bucket] = row
+        # Keep track of all of the unique column values for the group_by cols
+        @grouped_by_values.add @grouped_by.inject({}) { |h,col| h[col] = row.send(col); h }
+        self[row.time_bucket] = fetch(row.time_bucket, []) + [ row ]
       }
     end
-    
-    def fill_missing!(value=nil)
-      each_time { |key|
-        self[key] = value unless has_key?(key)
-      }
-      self
+
+    def self.create(relation)
+      if (relation.calculon_opts[:group_by] || []).length > 0
+        MultiGroupingResults.new(relation)
+      else
+        SingleGroupingResults.new(relation)
+      end
     end
 
-    def to_a
-      results = []
-      each_time { |key|
-        results << self[key] if self.has_key?(key)
-      }
-      results
+    def groupings
+      @grouped_by_values.to_a
     end
 
     def time_format
@@ -44,7 +46,7 @@ module Calculon
       }.fetch(@bucket_size)
     end
 
-    def each_time
+    def map_each_time
       increment_amounts = { :minute => 1.minute, :hour => 1.hour, :day => 1.day, :month => 1.month, :year => 1.year }
       increment = increment_amounts[@bucket_size]
 
@@ -52,10 +54,35 @@ module Calculon
       current = Time.zone.parse(@start_time.strftime(time_format + " %z"))
       last_time = Time.zone.parse(@end_time.strftime(time_format + " %z"))
 
+      results = []
       while current <= last_time
-        yield current.strftime(time_format)
+        results << yield(current.strftime(time_format))
         current += increment
       end
+      results
+    end
+  end
+
+  class SingleGroupingResults < Results
+    def to_a(default=nil)
+      map_each_time { |key|
+        fetch(key, [default]).first
+      }
+    end
+  end
+
+  class MultiGroupingResults < Results
+    def to_a
+      map_each_time { |key|
+        fetch(key, [])
+      }
+    end
+
+    def values_for(grouping, default=nil)
+      map_each_time { |key|
+        matches = fetch(key, []).select { |value| grouping.map { |k,v| value.send(k) == v }.all? }
+        matches.length > 0 ? matches.first : default
+      }
     end
   end
 end

data/lib/calculon/version.rb

@@ -1,3 +1,3 @@
 module Calculon
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/test/calculon_test.rb

@@ -37,18 +37,18 @@ class CalculonTest < Test::Unit::TestCase
     Game.create(:team_a_points => 30, :team_b_points => 40, :created_at => 2.hours.ago)
 
     assert_equal Game.by_hour(:team_a_points => :sum).length, 2
-    results = Game.points_by_hour.to_results_hash
+    results = Game.points_by_hour.to_buckets
     keys = [33.hours.ago.strftime("%Y-%m-%d %H:00:00"), 2.hours.ago.strftime("%Y-%m-%d %H:00:00")]
     assert_equal keys, results.keys.sort
-    assert_equal results[keys.first].team_a_points, 10 
-    assert_equal results[keys.last].team_b_points, 40 
+    assert_equal results[keys.first].first.team_a_points, 10 
+    assert_equal results[keys.last].first.team_b_points, 40 
 
     assert_equal Game.by_day(:team_a_points => :sum).length, 2
-    results = Game.points_by_day.to_results_hash
+    results = Game.points_by_day.to_buckets
     keys = [33.hours.ago.strftime("%Y-%m-%d 00:00:00"), 2.hours.ago.strftime("%Y-%m-%d 00:00:00")]
     assert_equal keys, results.keys.sort
-    assert_equal results[keys.first].team_a_points, 10 
-    assert_equal results[keys.last].team_b_points, 40     
+    assert_equal results[keys.first].first.team_a_points, 10 
+    assert_equal results[keys.last].first.team_b_points, 40     
   end
 
   def test_results_hash_missing

metadata

@@ -2,7 +2,7 @@
 name: calculon
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - Brian Muller
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2013-04-21 00:00:00 Z
+date: 2013-05-04 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rails
@@ -24,7 +24,7 @@ dependencies:
   prerelease: false
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: rdoc
+  name: yard
   requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -35,7 +35,7 @@ dependencies:
   prerelease: false
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
-  name: rake
+  name: redcarpet
   requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -46,7 +46,7 @@ dependencies:
   prerelease: false
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
-  name: sqlite3
+  name: rake
   requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -57,7 +57,7 @@ dependencies:
   prerelease: false
   version_requirements: *id004
 - !ruby/object:Gem::Dependency 
-  name: mysql2
+  name: sqlite3
   requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -67,6 +67,17 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: mysql2
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id006
 description: Calculon provides aggregate time functions for ActiveRecord.
 email: 
 - bamuller@gmail.com
@@ -85,8 +96,9 @@ files:
 - Rakefile
 - calculon.gemspec
 - lib/calculon.rb
+- lib/calculon/ext.rb
 - lib/calculon/railtie.rb
-- lib/calculon/summarized_results.rb
+- lib/calculon/results.rb
 - lib/calculon/version.rb
 - test/calculon_test.rb
 homepage: https://github.com/opbandit/calculon
@@ -102,7 +114,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 611864359157079367
+      hash: -4406503514097709404
       segments: 
       - 0
       version: "0"
@@ -111,7 +123,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 611864359157079367
+      hash: -4406503514097709404
       segments: 
       - 0
       version: "0"
@@ -124,3 +136,4 @@ specification_version: 3
 summary: Calculon provides aggregate time functions for ActiveRecord.
 test_files: 
 - test/calculon_test.rb
+has_rdoc: