gchart 0.4.2 → 0.5.0

data/CHANGELOG.txt

@@ -1,3 +1,15 @@
+== 0.5.0 (2008-05-11)
+
+  * Support for Map charts [Mark Thomas]
+  * Support for Sparkline charts [Mark Thomas]
+  * Initial support for Google-o-meter [Mark Thomas]
+  * Implemented both background solid fill and chart area solid fill.
+  * Added color aliasing: 3-character colors and a COLORS table.
+  * Full support for axis labels.
+  * Implemented horizontal/vertical range markers.
+  * New committer, Jim Ludwig.
+  * Freeze GChart::VERSION.
+
 == 0.4.2 (2008-01-09)
 
   * Encoding a flatlined chart doesn't asplode [Jack Danger Canty]

data/Manifest.txt

@@ -3,21 +3,41 @@ Manifest.txt
 README.txt
 Rakefile
 lib/gchart.rb
+lib/gchart/axis.rb
+lib/gchart/axis/bottom_axis.rb
+lib/gchart/axis/horizontal_axis.rb
+lib/gchart/axis/left_axis.rb
+lib/gchart/axis/right_axis.rb
+lib/gchart/axis/top_axis.rb
+lib/gchart/axis/vertical_axis.rb
 lib/gchart/bar.rb
 lib/gchart/base.rb
+lib/gchart/colors.rb
 lib/gchart/line.rb
+lib/gchart/map.rb
+lib/gchart/meter.rb
 lib/gchart/pie.rb
 lib/gchart/pie_3d.rb
 lib/gchart/scatter.rb
+lib/gchart/sparkline.rb
 lib/gchart/venn.rb
 lib/gchart/xy_line.rb
 lib/version.rb
+spec/gchart/axis/bottom_axis_spec.rb
+spec/gchart/axis/left_axis_spec.rb
+spec/gchart/axis/right_axis_spec.rb
+spec/gchart/axis/top_axis_spec.rb
+spec/gchart/axis_spec.rb
 spec/gchart/bar_spec.rb
 spec/gchart/base_spec.rb
+spec/gchart/colors_spec.rb
 spec/gchart/line_spec.rb
+spec/gchart/map_spec.rb
+spec/gchart/meter_spec.rb
 spec/gchart/pie_3d_spec.rb
 spec/gchart/pie_spec.rb
 spec/gchart/scatter_spec.rb
+spec/gchart/sparkline_spec.rb
 spec/gchart/venn_spec.rb
 spec/gchart/xy_line_spec.rb
 spec/gchart_spec.rb

data/README.txt

@@ -8,9 +8,9 @@ a friendly Ruby interface. It can generate the URL for a given chart
 
 == PROBLEMS/TODO
 
-* Add support fills (area or background), grid lines, shape markers, range markers 
-* Support shorthand colors and color names
+* Add grid lines, linear stripes, shape markers, gradient fills
 * Make venn data specification friendlier
+* Make documentation more digestible
 
 There are lots of missing features. Until they're implemented, you can directly specify
 query parameters using the :extras key, e.g.,
@@ -34,6 +34,12 @@ query parameters using the :extras key, e.g.,
   
   # scatter plot (x coords, y coords [, sizes])
   g = GChart.scatter(:data => [[1, 2, 3, 4, 5], [5, 4, 3, 2, 1], [1, 2, 3, 4, 5]])
+
+  # map chart
+  g = GChart.map(:area => 'usa', :data => {'NY'=>1,'VA'=>3,'CA'=>2})
+  
+  # meter
+  g = GChart.meter(:data => 70, :label => "70%")
   
   # chart title
   g = GChart.line(:title => "Awesomeness over Time", :data => [0, 10, 100])
@@ -49,11 +55,98 @@ query parameters using the :extras key, e.g.,
   g.write("foo.png")  # write to a file (defaults to "chart.png")
   g.write(stream)     # write to anything that quacks like IO
 
+== AXIS LABELING
+
+Charts which support an axis concept can be labeled. Supported types
+are line charts, bar charts, radar charts and scatter plots. See
++GChart::Axis+ for more information.
+
+== EXAMPLES
+
+=== Simple Line Chart with 2 data sets
+
+  require 'gchart'
+  chart = GChart.line do |g|
+    g.data   = [[0, 1, 2, 3, 4, 5, 6], [3, 2, 4, 1, 5, 0, 6]]
+    g.colors = [:red,                  :yellow]
+    g.legend = ["Line",                "Wonkiness"]
+
+    g.width  = 600
+    g.height = 150
+
+    g.entire_background = "f4f4f4"
+
+    g.axis(:left) { |a| a.range = 0..6 }
+
+    g.axis(:bottom) do |a|
+      a.labels          = ["Mon", "Tue", "Thu", "Sun"]
+      a.label_positions = [0,     16.67, 50,    100]
+      a.text_color = :black
+    end
+
+    g.axis(:bottom) do |a|
+      a.labels = ["Week 42"]
+      a.label_positions = [50]
+    end
+  end
+
+=== Complex Line Chart with multiple axes
+
+  require 'gchart'
+  chart = GChart.line do |g|
+    g.data   = [data_array1, data_array2, data_array3]
+    g.colors = [:red,        :green,      :blue]
+    g.legend = ["Set 1",     "Set 2",     "Set 3"]
+
+    g.width  = 950
+    g.height = 315
+
+    g.entire_background = "434"
+    g.chart_background  = "aba"
+
+    g.axis(:left) do |a|
+      a.range = 0..100
+      a.text_color = :red
+      a.font_size  = 9
+    end
+
+    g.axis(:right) do |a|
+      a.range = 0..1000
+      a.labels = %w(250 500 750)
+      a.label_positions = [250, 500, 750]
+
+      a.text_color = :green
+      a.font_size  = 8
+      a.text_alignment = :right
+    end
+
+    g.axis(:top) do |a|
+      a.labels = %w(2008)
+      a.positions = [50]
+    end
+
+    bottom1 = g.axis(:bottom)
+    bottom1.labels = dates_array
+    bottom1.range_markers = [
+      [0..33.33, 'ff000044'], [33.33..66.67, '00ff0044'], [66.67..100, '0000ff44']
+    ]
+
+    # We "manually" create our 2nd bottom axis...
+    bottom2 = GChart::Axis.create(:bottom)
+    bottom2.labels = %w(Dates)
+    bottom2.label_positions = [50]
+
+    # ...and therefore need to also add it to our axes "manually".
+    g.axes << bottom2
+  end
+
+  url = chart.to_url
+
 == LICENSE
 
 (The MIT License)
 
-Copyright 2007-2008 John Barnette (jbarnette@rubyforge.org)
+Copyright 2007-2008 John Barnette (jbarnette@rubyforge.org), Jim Ludwig (supplanter@rubyforge.org)
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/lib/gchart.rb

@@ -1,9 +1,15 @@
 require File.expand_path(File.dirname(__FILE__) + "/version")
+require File.expand_path(File.dirname(__FILE__) + "/gchart/colors")
+require File.expand_path(File.dirname(__FILE__) + "/gchart/axis")
 
-%w(base bar line pie pie_3d scatter venn xy_line).each do |type|
+%w(base bar line map meter pie pie_3d scatter sparkline venn xy_line).each do |type|
   require File.expand_path(File.dirname(__FILE__) + "/gchart/#{type}")
 end
 
+%w(horizontal vertical top right bottom left).each do |type|
+  require File.expand_path(File.dirname(__FILE__) + "/gchart/axis/#{type}_axis")
+end
+
 module GChart
   URL   = "http://chart.apis.google.com/chart"
   SIMPLE_CHARS = ('A'..'Z').to_a + ('a'..'z').to_a + ('0'..'9').to_a
@@ -20,18 +26,27 @@ module GChart
     # Convenience constructor for GChart::Bar.
     def bar(*args, &block); Bar.new(*args, &block) end    
     
+    # Convenience constructor for GChart::Map.
+    def map(*args, &block); Map.new(*args, &block) end    
+
+    # Convenience constructor for GChart::Meter.
+    def meter(*args, &block); Meter.new(*args, &block) end    
+
     # Convenience constructor for GChart::Pie.
     def pie(*args, &block); Pie.new(*args, &block) end    
     
     # Convenience constructor for GChart::Pie3D.
     def pie3d(*args, &block); Pie3D.new(*args, &block) end    
     
-    # Convenience constructor for GChart::Venn.
-    def venn(*args, &block); Venn.new(*args, &block) end    
-    
     # Convenience constructor for GChart::Scatter.
     def scatter(*args, &block); Scatter.new(*args, &block) end
     
+    # Convenience constructor for GChart::Sparkline.
+    def sparkline(*args, &block); Sparkline.new(*args, &block) end
+
+    # Convenience constructor for GChart::Venn.
+    def venn(*args, &block); Venn.new(*args, &block) end    
+        
     # Encode +n+ as a string. +n+ is normalized based on +max+.
     # +encoding+ can currently only be :extended.
     def encode(encoding, n, max)

data/lib/gchart/axis.rb

@@ -0,0 +1,139 @@
+module GChart
+  class Axis
+
+    # Array of axis labels. Can be exactly placed along the axis with
+    # +label_positions+, otherwise are evenly spaced.
+    attr_accessor :labels
+
+    # Array of float positions for +labels+. Without +labels+, the
+    # +label_positions+ are self-labeling.
+    attr_accessor :label_positions
+
+    # Takes a +Range+ of float values. With +labels+, defines +labels+
+    # context, meaning the +labels+ will be spaced at their proper
+    # location within the +range+. Without +labels+, smart-labeling
+    # occurs for +range+.
+    attr_accessor :range
+
+    # An rrggbb color for axis text.
+    attr_accessor :text_color
+
+    # Size of font in pixels. To set +font_size+, +text_color+ is also
+    # required.
+    attr_accessor :font_size
+
+    # +TEXT_ALIGNMENT+ property for axis labeling. To set
+    # +text_alignment+, both +text_color+ and +font_size+ must also be
+    # set.
+    attr_accessor :text_alignment
+
+    # Array of 2-element sub-arrays such that the 1st element in each
+    # sub-array is a +Range+ of float values which describe the start
+    # and end points of the range marker, and the 2nd element in each
+    # sub-array is an rrggbb color for the range marker.  For +:top+
+    # and +:bottom+ +AXIS_TYPES+, markers are vertical. For +:right+
+    # and +:left+ +AXIS_TYPES+, markers are horizontal.
+    attr_accessor :range_markers
+
+    AXIS_TYPES = [ :top, :right, :bottom, :left ]
+
+    # Defaults: +:left+ for +RightAxis+, +:center+ for +TopAxis+ and
+    # for +BottomAxis+, and +:right+ for +LeftAxis+.
+    TEXT_ALIGNMENT = { :left => -1, :center => 0, :right => 1 }
+
+    class << self
+      # Instantiates the proper +GChart::Axis+ subclass based on the
+      # +axis_type+.
+      def create(axis_type, &block)
+        raise ArgumentError.new("Invalid axis type '#{axis_type}'") unless AXIS_TYPES.include?(axis_type)
+
+        axis = Object.module_eval("GChart::#{axis_type.to_s.capitalize}Axis").new
+
+        yield(axis) if block_given?
+        axis
+      end
+
+      private :new
+    end
+
+    def initialize
+      @labels          = []
+      @label_positions = []
+      @range_markers   = {}
+    end
+
+    # Returns a one-character label of the axis according to its type.
+    def axis_type_label
+      raise NotImplementedError.new("Method must be overridden in a subclass of this abstract base class.")
+    end
+
+    # Returns a one-character label to indicate whether
+    # +ranger_markers+ are vertical or horizontal.
+    def range_marker_type_label
+      raise NotImplementedError.new("Method must be overridden in a subclass of this abstract base class.")
+    end
+
+    # Ensures that all combinations of attributes which have been set
+    # will work with each other. Raises +ArgumentError+ otherwise.
+    def validate!
+      if labels.size > 0 and label_positions.size > 0 and labels.size != label_positions.size
+        raise ArgumentError.new(
+          "Both labels and label_positions have been specified, but their " +
+          "respective counts do not match (labels.size = '#{labels.size}' " +
+          "and label_positions.size = '#{label_positions.size}')"
+        )
+      end
+
+      unless label_positions.all? { |pos| pos.is_a?(Numeric) }
+        raise ArgumentError.new(
+          "The label_positions attribute requires numeric values for each position specified"
+        )
+      end
+
+      if range
+        unless range.is_a?(Range)
+          raise ArgumentError.new("The range attribute has been specified with a non-Range class")
+        end
+
+        unless range.first.is_a?(Numeric)
+          raise ArgumentError.new("The range attribute has been specified with non-numeric range values")
+        end
+      end
+
+      if font_size and not text_color
+        raise ArgumentError.new("To specify a font_size, a text_color must also be specified")
+      end
+
+      if text_alignment and not (text_color and font_size)
+        raise ArgumentError.new(
+          "To specify a text_alignment, both text_color and font_size must also be specified"
+        )
+      end
+
+      if text_color and not GChart.valid_color?(text_color)
+        raise ArgumentError.new("The text_color attribute has been specified with an invalid color")
+      end
+
+      if font_size and not font_size.is_a?(Numeric)
+        raise ArgumentError.new("The font_size must have a numeric value")
+      end
+
+      if text_alignment and not TEXT_ALIGNMENT[text_alignment]
+        raise ArgumentError.new(
+          "The text_alignment attribute has been specified with a non-TEXT_ALIGNMENT"
+        )
+      end
+
+      if not range_markers.all? { |array| array.is_a?(Array) and array.size == 2 and
+                                          array[0].is_a?(Range) and array[0].first.is_a?(Numeric) and
+                                          GChart.valid_color?(array[1]) }
+        raise ArgumentError.new(
+          "The range_markers attribute must be an array of 2-element sub-arrays such that " +
+          "the first element in each sub-array is a Range of numeric values and the second " +
+          "element in each sub-array is a valid color"
+        )
+      end
+    end
+
+  end
+end

data/lib/gchart/axis/bottom_axis.rb

@@ -0,0 +1,10 @@
+module GChart
+  class BottomAxis < HorizontalAxis
+    # Returns 'x'.
+    def axis_type_label
+      'x'
+    end
+
+    class << self ; public :new ; end
+  end
+end

data/lib/gchart/axis/horizontal_axis.rb

@@ -0,0 +1,11 @@
+module GChart
+  class HorizontalAxis < Axis
+    # Returns 'R' to indicate a vertical +range_marker+ (stemming
+    # from a horizontal axis).
+    def range_marker_type_label
+      'R'
+    end
+
+    class << self ; private :new ; end
+  end
+end

data/lib/gchart/axis/left_axis.rb

@@ -0,0 +1,10 @@
+module GChart
+  class LeftAxis < VerticalAxis
+    # Returns 'y'.
+    def axis_type_label
+      'y'
+    end
+
+    class << self ; public :new ; end
+  end
+end

data/lib/gchart/axis/right_axis.rb

@@ -0,0 +1,10 @@
+module GChart
+  class RightAxis < VerticalAxis
+    # Returns 'r'.
+    def axis_type_label
+      'r'
+    end
+
+    class << self ; public :new ; end
+  end
+end

data/lib/gchart/axis/top_axis.rb

@@ -0,0 +1,10 @@
+module GChart
+  class TopAxis < HorizontalAxis
+    # Returns 't'.
+    def axis_type_label
+      't'
+    end
+
+    class << self ; public :new ; end
+  end
+end

data/lib/gchart/axis/vertical_axis.rb

@@ -0,0 +1,11 @@
+module GChart
+  class VerticalAxis < Axis
+    # Returns 'r' to indicate a horizontal +range_marker+ (stemming
+    # from a vertical axis).
+    def range_marker_type_label
+      'r'
+    end
+
+    class << self ; private :new ; end
+  end
+end

data/lib/gchart/base.rb

@@ -5,31 +5,44 @@ module GChart
   class Base
     # Array of chart data. See subclasses for specific usage.
     attr_accessor :data
-    
+
     # Hash of additional HTTP query params.
     attr_accessor :extras
-    
+
     # Chart title.
     attr_accessor :title
-    
+
     # Array of rrggbb colors, one per data set.
     attr_accessor :colors
-    
+
     # Array of legend text, one per data set.
     attr_accessor :legend
-    
+
     # Max data value for quantization.
     attr_accessor :max
 
     # Chart width, in pixels.
-    attr_reader :width    
-    
+    attr_reader :width
+
     # Chart height, in pixels.
     attr_reader :height
 
+    # Background rrggbb color of entire chart image.
+    attr_accessor :entire_background
+
+    # Background rrggbb color of just chart area of chart image.
+    attr_accessor :chart_background
+
+    # Array of +GChart::Axis+ objects.
+    attr_accessor :axes
+
     def initialize(options={}, &block)
-      @data = []
+      @data   = []
+      @colors = []
+      @legend = []
+      @axes   = []
       @extras = {}
+
       @width = 300
       @height = 200
   
@@ -51,9 +64,9 @@ module GChart
     # if +height+ is less than 1 or greater than 1,000.
     def height=(height)
       if height.nil? || height < 1 || height > 1_000
-        raise ArgumentError, "Invalid height: #{height.inspect}"         
+        raise ArgumentError, "Invalid height: #{height.inspect}"
       end
-      
+
       @height = height
     end
 
@@ -66,7 +79,7 @@ module GChart
     # if +width+ * +height+ is greater than 300,000 pixels.
     def size=(size)
       self.width, self.height = size.split("x").collect { |n| Integer(n) }
-      
+
       if (width * height) > 300_000
         raise ArgumentError, "Invalid size: #{size.inspect} yields a graph with more than 300,000 pixels"
       end
@@ -90,6 +103,14 @@ module GChart
       open(io_or_file, "w+") { |io| io.write(fetch) }
     end
 
+    # Adds an +axis_type+ +GChart::Axis+ to the chart's set of
+    # +axes+. See +GChart::Axis::AXIS_TYPES+.
+    def axis(axis_type, &block)
+      axis = GChart::Axis.create(axis_type, &block)
+      @axes.push(axis)
+      axis
+    end
+
     protected
     
     def query_params(raw_params={}) #:nodoc:
@@ -99,6 +120,13 @@ module GChart
       render_title(params)
       render_colors(params)
       render_legend(params)
+      render_backgrounds(params)
+
+      unless @axes.empty?
+        if is_a?(GChart::Line) or is_a?(GChart::Bar) or is_a?(GChart::Scatter) # or is_a?(GChart::Radar)
+          render_axes(params)
+        end
+      end
 
       params.merge(extras)
     end
@@ -110,24 +138,127 @@ module GChart
     def render_data(params) #:nodoc:
       raw = data && data.first.is_a?(Array) ? data : [data]
       max = self.max || raw.collect { |s| s.max }.max
-  
+
       sets = raw.collect do |set|
         set.collect { |n| GChart.encode(:extended, n, max) }.join
       end
-  
       params["chd"] = "e:#{sets.join(",")}"
     end
     
     def render_title(params) #:nodoc:
       params["chtt"] = title.tr("\n ", "|+") if title
     end
-    
+
     def render_colors(params) #:nodoc:
-      params["chco"] = colors.join(",") if colors  
+      unless colors.empty?
+        params["chco"] = colors.collect{ |color| GChart.expand_color(color) }.join(",")
+      end
     end
-    
+
     def render_legend(params) #:nodoc:
-      params["chdl"] = legend.join("|") if legend
-    end    
+      params["chdl"] = legend.join("|") unless legend.empty?
+    end
+
+    def render_backgrounds(params) #:nodoc:
+      if entire_background || chart_background
+        if entire_background and not GChart.valid_color?(entire_background)
+          raise ArgumentError.new("The entire_background attribute has an invalid color")
+        end
+        if chart_background and not GChart.valid_color?(chart_background)
+          raise ArgumentError.new("The chart_background attribute has an invalid color")
+        end
+
+        separator = entire_background && chart_background ? "|" : ""
+        params["chf"]  = entire_background ? "bg,s,#{GChart.expand_color(entire_background)}" : ""
+        params["chf"] += "#{separator}c,s,#{GChart.expand_color(chart_background)}" if chart_background
+      end
+    end
+
+    def render_axes(params) #:nodoc:
+      @axes.each do |axis|
+        axis.validate!
+      end
+
+      render_axis_type_labels(params)
+      render_axis_labels(params)
+      render_axis_label_positions(params)
+      render_axis_ranges(params)
+      render_axis_styles(params)
+      render_axis_range_markers(params)
+    end
+
+    def render_axis_type_labels(params) #:nodoc:
+      params["chxt"] = @axes.collect{ |axis| axis.axis_type_label }.join(',')
+    end
+
+    def render_axis_labels(params) #:nodoc:
+      if @axes.any?{ |axis| axis.labels.size > 0 }
+        chxl = []
+
+        @axes.each_with_index do |axis, index|
+          if axis.labels.size > 0
+            chxl.push("#{index}:")
+            chxl += axis.labels
+          end
+        end
+
+        params["chxl"] = chxl.join('|')
+      end
+    end
+
+    def render_axis_label_positions(params) #:nodoc:
+      if @axes.any?{ |axis| axis.label_positions.size > 0 }
+        chxp = []
+
+        @axes.each_with_index do |axis, index|
+          chxp.push("#{index}," + axis.label_positions.join(',')) if axis.label_positions.size > 0
+        end
+
+        params["chxp"] = chxp.join('|')
+      end
+    end
+
+    def render_axis_ranges(params) #:nodoc:
+      if @axes.any?{ |axis| axis.range }
+        chxr = []
+
+        @axes.each_with_index do |axis, index|
+          chxr.push("#{index},#{axis.range.first},#{axis.range.last}") if axis.range
+        end
+
+        params["chxr"] = chxr.join('|')
+      end
+    end
+
+    def render_axis_styles(params) #:nodoc:
+      if @axes.any?{ |axis| axis.text_color }
+        chxs = []
+
+        @axes.each_with_index do |axis, index|
+          if axis.text_color
+            chxs.push(
+              "#{index}," +
+              [GChart.expand_color(axis.text_color), axis.font_size, axis.text_alignment].compact.join(',')
+            )
+          end
+        end
+
+        params["chxs"] = chxs.join('|')
+      end
+    end
+
+    def render_axis_range_markers(params) #:nodoc:
+      if @axes.any?{ |axis| axis.range_markers.size > 0 }
+        chmr = []
+
+        @axes.each do |axis|
+          axis.range_markers.each do |range, color|
+            chmr.push("#{axis.range_marker_type_label},#{color},0,#{range.first},#{range.last}")
+          end
+        end
+
+        params["chm"] = chmr.join('|')
+      end
+    end
   end
 end