graphene 0.0.1 → 0.0.2

data/README.rdoc

@@ -51,6 +51,15 @@ See Graphene.percentages for more info.
 
 Same as percentages above, except that subtotals are returned instead. See Graphene.subtotals for more info.
 
+== Adding a dimension
+
+Marty, you're not thinking fourth-dimensionally!
+
+    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]]}
+
 == Tablizer
 
 Integration with the tablizer gem provides quick ASCII tables.
@@ -89,7 +98,11 @@ 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 http://gruff.rubyforge.org/classes/Gruff/Base.html for more Gruff options.
+See Graphene::OneDGraphs and Graphene::TwoDGraphs for more 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
 

data/lib/graphene/gruff.rb

@@ -316,6 +316,80 @@ module Graphene
     end
     alias_method :net_chart, :net_graph
 
+    # Returns a Gruff::Dot object with the stats set.
+    #
+    # Optionally you may pass a file path and graph title. If you pass a file path, the graph will
+    # be written to file automatically. Otherwise, you would call "write('/path/to/graph.png')" on the
+    # returned graph object.
+    #
+    # If you pass a block, it will be called, giving you access to the Gruff::Dot object before it is
+    # written to file (that is, if you also passed a file path). It will also give you access to a Proc
+    # for labeling the X axis.
+    #
+    # Example 1:
+    # 
+    #  Graphene.percentages(logs, :browser).over(:date).dot_graph('/path/to/browser-share.png', 'Browser Share')
+    #
+    # Example 2:
+    #
+    #  Graphene.subtotals(logs, :browser).over(:date).dot_graph('/path/to/browser-share.png') do |chart, labeler|
+    #    chart.title = 'Browser Share'
+    #    chart.font = '/path/to/font.ttf'
+    #    chart.theme = pie.theme_37signals
+    #  end
+    #
+    # Example 3:
+    #
+    #  Graphene.subtotals(logs, :browser).over(:date).dot_graph('/path/to/browser-share.png') do |chart, labeler|
+    #    chart.title = 'Browser Share'
+    #
+    #    # Both the 10 and the block are optional.
+    #    #  - "10" means that only every 10'th label will be printed. Otherwise, each would be.
+    #    #  - The block is passed each label (the return value of the "over attribute") and may return a formatted version.
+    #    labeler.call(10) do |date|
+    #      date.strftime('%m/%d/%Y')
+    #    end
+    #  end
+    #
+    # Example 4:
+    #
+    #  Graphene.percentages(logs, :platform, :browser).over(->(l) { l.date.strftime('%m/%Y') }).dot_graph('/path/to/os-browser-share.png', 'OS / Browser Share by Month')
+    #
+    def dot_graph(path=nil, title=nil, &block)
+      Graphene.gruff do
+        graph(Gruff::Dot.new, path, title, &block)
+      end
+    end
+    alias_method :dot_chart, :dot_graph
+
+    # Returns a Gruff::AccumulatorBar object with the stats set. This is different than most other graphs in that it may only 
+    # have one row of data. For example, if you limit the browser to Firefox, it could show the relative gains in Firefox
+    # usage over time. You might start out with:
+    #
+    # Optionally you may pass a file path and graph title. If you pass a file path, the graph will
+    # be written to file automatically. Otherwise, you would call "write('/path/to/graph.png')" on the
+    # returned graph object.
+    #
+    # If you pass a block, it will be called, giving you access to the Gruff::AccumulatorBar object before it is
+    # written to file (that is, if you also passed a file path). It will also give you access to a Proc
+    # for labeling the X axis.
+    # 
+    # Example:
+    # 
+    #  logs = SomeLogParser.parse('/logs/*').select { |log| log.browser == 'Firefox' }
+    #  Graphene.subtotals(logs, :browser).over(:date).accumulator_bar_graph('/path/to/firefox-share.png', 'Firefox Share')
+    #
+    def accumulator_bar_graph(path=nil, title=nil, &block)
+      Graphene.gruff do
+        begin
+          graph(Gruff::AccumulatorBar.new, path, title, &block)
+        rescue Gruff::IncorrectNumberOfDatasetsException => e
+          raise GrapheneException, "An Accumulator Bar Graph may only have one row of data - #{e.class.name}"
+        end
+      end
+    end
+    alias_method :accumulator_bar_chart, :accumulator_bar_graph
+
     private
 
     # Builds a graph

data/lib/graphene/version.rb

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

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Jordan Hollinger
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-07-22 00:00:00 -04:00
+date: 2012-07-23 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -43,12 +43,11 @@ files:
 - lib/graphene.rb
 - lib/graphene/graphene.rb
 - lib/graphene/gruff.rb
-- lib/graphene/gruff_helpers.rb
+- lib/graphene/version.rb
 - lib/graphene/percentages.rb
 - lib/graphene/result_set.rb
 - lib/graphene/subtotals.rb
 - lib/graphene/tablizer.rb
-- lib/graphene/version.rb
 - lib/graphene/over_x.rb
 - lib/graphene/lazy_enumerable.rb
 - README.rdoc