graphene 0.0.2 → 0.1.0

data/README.rdoc

@@ -5,8 +5,6 @@ It's most useful feature is probably the Gruff helpers. True, some types of Gruf
 with, but others can require tedious boilerplate code to calculate percentages, well-spaced labels, and more.
 Graphene hides all of that, accepting an array of objects and transforming them into a graph.
 
-Read the full documentation at http://jordanhollinger.com/docs/graphene/.
-
 Nobody likes you, Ruby 1.8. Now go away.
 
 == Installation
@@ -35,8 +33,8 @@ See http://nubyonrails.com/pages/gruff/ for more on Gruff.
     puts percentages.to_a
     => [["Firefox", 40.0], ["Chrome", 35.0], ["Internet Explorer", 25.0]]
 
-    percentages.each do |browser, count|
-      puts "There were #{count} hits from #{browser}"
+    percentages.each do |browser, percent|
+      puts "#{percent}% of hits were from from #{browser}"
     end
 
     # You can also calculate by multiple criteria, and may use lambdas instead of symbols
@@ -53,18 +51,30 @@ Same as percentages above, except that subtotals are returned instead. See Graph
 
 == Adding a dimension
 
-Marty, you're not thinking fourth-dimensionally!
+"Marty, you're not thinking fourth-dimensionally!" This is only three dimensions, but whatever, Doc.
 
     puts Graphene.percentages(logs, :browser).over(:date)
     => {#<Date: 2012-07-22> => [["Firefox", 45], ["Chrome", 40], ["Internet Explorer", 15]],
-        #<Date: 2012-07-23> => [["Firefox", 41], ["Chrome", 40], ["Internet Explorer", 19]],
-        #<Date: 2012-07-24> => [["Chrome", 50], ["Firefox", 40], ["Internet Explorer", 10]]}
+        #<Date: 2012-07-23> => [],
+        #<Date: 2012-07-24> => [["Firefox", 41], ["Chrome", 40], ["Internet Explorer", 19]],
+        #<Date: 2012-07-25> => [["Chrome", 50], ["Firefox", 40], ["Internet Explorer", 10]]}
+
+Notice that in the results above, there were no log entries on 2012-07-23. So how did Graphene know to include that date? Because dates are iterable.
+If your X axis objects are *not* iterable and you want to ensure that none are left out, you can provide them yourself:
+
+    # Ryan didn't make any sales, so he won't show up unless we include his name
+    puts Graphene.subtotals(sales, :reams).over(:name, ['Jim', 'Dwight', 'Ryan'])
+
+    # Ruby doesn't know how to iterate months, but you do
+    puts Graphene.percentages(logs, :browser).over(->(log) { [log.date.month, log.date.year] }) do |month, year|
+      month < 12 ? [month + 1, year] : [1, year + 1]
+    end
 
 == Tablizer
 
 Integration with the tablizer gem provides quick ASCII tables.
 
-    puts percentages.tablize
+    puts Graphene.percentages(logs, :browser, :platform).tablize
     => +-----------------+------------+----------+
        |     Browser     |  Platform  |Percentage|
        +-----------------+------------+----------+
@@ -98,16 +108,12 @@ Provides helpers for generating Gruff graphs. Requires the "gruff" Ruby gem.
       end
     end
 
-See Graphene::OneDGraphs and Graphene::TwoDGraphs for more types and examples.
+See Graphene::OneDGraphs, Graphene::TwoDGraphs and http://jordanhollinger.com/2012/07/23/introducing-graphene for more graph types and examples.
 
 See http://www.ruby-doc.org/gems/docs/f/fhs-gruff-0.3.6.2/README_txt.html for more on Gruff.
 Specifically, http://www.ruby-doc.org/gems/docs/f/fhs-gruff-0.3.6.2/Gruff/Base.html will let 
 you know many things that can be customized in the optional block.
 
-== TODO
-
-Graphene::OverX and the graph helpers needs the ability to fill in empty points
-
 == License
 Copyright 2012 Jordan Hollinger
 

data/lib/graphene.rb

@@ -2,8 +2,7 @@
 require 'tablizer'
 begin
   require 'gruff'
-rescue LoadError => e
-  $stderr.puts "NOTICE Graphene cannot find Gruff; graphing will not be not available. Install the \"gruff\" gem in enable it."
+rescue LoadError
 end
 
 require 'graphene/version'
@@ -14,7 +13,7 @@ require 'graphene/tablizer'
 require 'graphene/gruff'
 
 # Calculators
-require 'graphene/lazy_enumerable'
+require 'lazy_enumerable'
 require 'graphene/result_set'
 require 'graphene/subtotals'
 require 'graphene/percentages'

data/lib/graphene/gruff.rb

@@ -1,13 +1,29 @@
 module Graphene
+  class << self
+    # The default Gruff font path
+    attr_accessor :font
+
+    # The default Gruff theme
+    attr_accessor :theme
+  end
+
   # Executes the given block if Gruff is available. Raises a GrapheneException if not.
   def self.gruff
     if defined? Gruff
       yield if block_given?
     else
-      raise GrapheneException, "Gruff integration is disabled because Gruff could not be loaded; install the \"gruff\" gem"
+      raise GrapheneException, 'Gruff integration is disabled because Gruff could not be found; bundle or install the "rmagick" and "gruff" gems to enable it'
     end
   end
 
+  private
+
+  # Apply the default theme and font to the given Gruff chart
+  def self.theme!(chart)
+    chart.font = self.font if self.font
+    chart.theme = self.theme if self.theme
+  end
+
   # Extends calculators with one-dimensional graphs, like pie charts.
   module OneDGraphs
     # Returns a Gruff::Pie object with the stats set.
@@ -206,6 +222,7 @@ module Graphene
 
     # Builds a chart
     def chart(chart, path=nil, title=nil, hack=false, &block)
+      Graphene.theme! chart
       chart.title = title unless title.nil?
       block.call(chart) if block
 
@@ -394,6 +411,7 @@ module Graphene
 
     # Builds a graph
     def graph(graph, path=nil, title=nil, &block)
+      Graphene.theme! graph
       graph.title = title unless title.nil?
 
       # Create an empty array for each group (e.g. {["Firefox"] => [], ["Safari"] => []}), even if it's empty.

data/lib/graphene/over_x.rb

@@ -8,7 +8,14 @@ module Graphene
   #      #<Date: 2012-07-23> => [["Firefox", 41], ["Chrome", 40], ["Internet Explorer", 19]],
   #      #<Date: 2012-07-24> => [["Chrome", 50], ["Firefox", 40], ["Internet Explorer", 10]]}
   #
-  # See Graphene::LazyEnumerable, Graphene::Tablize and Graphene::TwoDGraphs for more documentation.
+  # See LazyEnumerable, Graphene::Tablize and Graphene::TwoDGraphs for more documentation.
+  # 
+  # If your X objects can be put into a range, Graphene will attempt to fill in any gaps along the X axis.
+  # But if they can't be ranged (e.g. formatted strings), you have several options to fill them in yourself:
+  # 
+  #  Graphene.percentages(logs, :browser).over(->(l) { l.date.strftime('%B %Y') }, [an array of all month/year in the logs])
+  #  Graphene.percentages(logs, :browser).over(->(l) { l.date.strftime('%B %Y') }) { |str| somehow parse the month/year and return the next one }
+  # 
   class OverX
     include LazyEnumerable
     include TwoDGraphs
@@ -18,9 +25,10 @@ module Graphene
 
     # Accepts a ResultSet object (i.e. Graphene::Subtotals or Graphene::Percentages), and a
     # method symbol or proc/lambda to build the X axis
-    def initialize(result_set, attr_or_lambda)
+    def initialize(result_set, attr_or_lambda, filler=nil, &filler_block)
       @result_set = result_set
       @attribute = attr_or_lambda
+      @filler = filler_block || filler
       @results = {}
     end
 
@@ -38,12 +46,52 @@ module Graphene
 
     # Run the calculation
     def enumerate!
+      # Group all the objects by X
       resources_by_x = result_set.resources.group_by(&@attribute).sort_by(&:first)
-      @results = resources_by_x.inject({}) do |results, (x, group)|
+      # Attempt to retrieve or calculate all possible X points, so there are no gaps
+      x_points_hash = Hash[x_points(resources_by_x).map { |x| [x, []] }]
+      # Distribute the objects across the X points
+      @results = resources_by_x.inject(x_points_hash) do |results, (x, group)|
         results[x] ||= []
         results[x] += result_set.class.new(group, *result_set.attributes).to_a
         results
       end
     end
+
+    # Returns an array of all pre-calculated (or provided) X points. Attempts to fill in any gaps.
+    def x_points(resources_by_x)
+      first_x = resources_by_x.first ? resources_by_x.first.first : nil
+      last_x = resources_by_x.last ? resources_by_x.last.first : nil
+
+      # A range from the first to last point (multi-char strings are excluded, because a range of those is usually not what you want)
+      if @filler.nil? and first_x.respond_to? :succ and first_x.respond_to? :"<=>" and (!first_x.is_a?(String) or first_x.size == 1)
+        (first_x..last_x).to_a
+      # An array
+      elsif @filler.respond_to? :to_a
+        @filler.to_a
+      # A block
+      elsif @filler.respond_to? :call
+        keys = resources_by_x.map(&:first)
+        keys.each_with_index.to_a.inject([]) do |points, (key, i)|
+          points << key
+          # Fill in any gaps between this point and the next
+          if next_available_key = keys[i+1]
+            next_calculated_key = key
+            while next_calculated_key != next_available_key
+              # Try to prevent an infinite loop if someone does something dumb
+              if next_calculated_key.respond_to? :"<"
+                break unless next_calculated_key < next_available_key
+              end
+              points << next_calculated_key
+              next_calculated_key = @filler.call(next_calculated_key) 
+            end
+          end
+          points
+        end
+      # Can't do it, so there may be gaps
+      else
+        []
+      end
+    end
   end
 end

data/lib/graphene/percentages.rb

@@ -2,7 +2,7 @@ require 'graphene/subtotals'
 
 module Graphene
   # Calculates and contains the percent subtotals of each attr (or attr group). Inherits from Graphene::ResultSet.
-  # See Graphene::LazyEnumerable, Graphene::Tablize and Graphene::OneDGraphs for more documentation.
+  # See LazyEnumerable, Graphene::Tablize and Graphene::OneDGraphs for more documentation.
   # 
   # If you passed an options Hash containing :threshold to the constructor, 
   # any results falling below it will be excluded.

data/lib/graphene/result_set.rb

@@ -1,5 +1,5 @@
 module Graphene
-  # A generic class for Graphene stat result sets, which implements Enumerable and Graphene::LazyEnumerable.
+  # A generic class for Graphene stat result sets, which implements Enumerable and LazyEnumerable.
   # Calculations are performed lazily, so ResultSet objects are *cheap to create, but not necessarily cheap to use*.
   class ResultSet
     include LazyEnumerable
@@ -32,9 +32,15 @@ module Graphene
     #  => {#<Date: 2012-07-22> => [["Firefox", 45], ["Chrome", 40], ["Internet Explorer", 15]],
     #      #<Date: 2012-07-23> => [["Firefox", 41], ["Chrome", 40], ["Internet Explorer", 19]],
     #      #<Date: 2012-07-24> => [["Chrome", 50], ["Firefox", 40], ["Internet Explorer", 10]]}
+    # 
+    # If your X objects can be put into a range, Graphene will attempt to fill in any gaps along the X axis.
+    # But if they can't be ranged (e.g. formatted strings), you have several options to fill them in yourself:
+    # 
+    #  Graphene.percentages(logs, :browser).over(->(l) { l.date.strftime('%B %Y') }, [an array of all month/year in the logs])
+    #  Graphene.percentages(logs, :browser).over(->(l) { l.date.strftime('%B %Y') }) { |str| somehow parse the month/year and return the next one }
     #
-    def over(over_x)
-      OverX.new(self, over_x)
+    def over(over_x, filler=nil, &filler_block)
+      OverX.new(self, over_x, filler, &filler_block)
     end
 
     # Returns a string representation of the results

data/lib/graphene/subtotals.rb

@@ -2,7 +2,7 @@ require 'graphene/result_set'
 
 module Graphene
   # Calculates and contains the subtotals of each attr (or attr group). Inherits from Graphene::ResultSet.
-  # See Graphene::LazyEnumerable, Graphene::Tablize and Graphene::OneDGraphs for more documentation.
+  # See LazyEnumerable, Graphene::Tablize and Graphene::OneDGraphs for more documentation.
   # 
   # Don't create instance manually. Instead, use the Graphene.subtotals method, which will return
   # a properly instantiated object.

data/lib/graphene/version.rb

@@ -1,4 +1,4 @@
 module Graphene
   # Version number
-  VERSION = '0.0.2'
+  VERSION = '0.1.0'
 end

data/lib/lazy_enumerable.rb

@@ -0,0 +1,31 @@
+# Includes Enumerable and alculates @results lazily. An enumerate! method must be implemented.
+module LazyEnumerable
+  def self.included(base) # :nodoc:
+    base.send(:include, Enumerable)
+  end
+
+  # Implements the "each" method required by Enumerable.
+  def each(&block)
+    lazily_enumerate!
+    @results.each &block
+  end
+
+  # Tests equality between this and another set
+  def ==(other)
+    lazily_enumerate!
+    to_a == other.to_a
+  end
+
+  # Tests equality between this and another set
+  def ===(other)
+    lazily_enumerate!
+    to_a === other.to_a
+  end
+
+  private
+
+  # Run the calculation if it hasn't already been
+  def lazily_enumerate!
+    enumerate! if @results.empty?
+  end
+end

metadata

@@ -1,88 +1,73 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: graphene
-version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 0
-  - 0
-  - 2
-  version: 0.0.2
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Jordan Hollinger
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-07-23 00:00:00 -04:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-11-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: tablizer
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 1
-        - 0
-        version: "1.0"
+      - !ruby/object:Gem::Version
+        version: '1.0'
   type: :runtime
-  version_requirements: *id001
-description: Library for calculating subtotals, percentages, tables and graphs from collections of Ruby objects
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Library for calculating subtotals, percentages, tables and graphs from
+  collections of Ruby objects
 email: jordan@jordanhollinger.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - lib/graphene.rb
-- lib/graphene/graphene.rb
-- lib/graphene/gruff.rb
-- lib/graphene/version.rb
-- lib/graphene/percentages.rb
-- lib/graphene/result_set.rb
+- lib/graphene/over_x.rb
 - lib/graphene/subtotals.rb
 - lib/graphene/tablizer.rb
-- lib/graphene/over_x.rb
-- lib/graphene/lazy_enumerable.rb
+- lib/graphene/version.rb
+- lib/graphene/graphene.rb
+- lib/graphene/result_set.rb
+- lib/graphene/percentages.rb
+- lib/graphene/gruff.rb
+- lib/lazy_enumerable.rb
 - README.rdoc
 - LICENSE
-has_rdoc: true
 homepage: http://github.com/jhollinger/graphene
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Easily create stats and graphs from collections of Ruby objects
 test_files: []
-

data/lib/graphene/lazy_enumerable.rb

@@ -1,33 +0,0 @@
-module Graphene
-  # Includes Enumerable and alculates @results lazily. An enumerate! method must be implemented.
-  module LazyEnumerable
-    def self.included(base) # :nodoc:
-      base.send(:include, Enumerable)
-    end
-
-    # Implements the "each" method required by Enumerable.
-    def each(&block)
-      lazily_enumerate!
-      @results.each &block
-    end
-
-    # Tests equality between this and another set
-    def ==(other)
-      lazily_enumerate!
-      to_a == other.to_a
-    end
-
-    # Tests equality between this and another set
-    def ===(other)
-      lazily_enumerate!
-      to_a === other.to_a
-    end
-
-    private
-
-    # Run the calculation if it hasn't already been
-    def lazily_enumerate!
-      enumerate! if @results.empty?
-    end
-  end
-end