gregoryfoster-gchartrb 0.9

data/lib/google_chart/base.rb

@@ -0,0 +1,148 @@
+require 'open-uri'
+require 'uri'
+
+module GoogleChart
+  class Base
+    # Make new method private to avoid direct initialisation
+    class <<self ; private :new ; end
+
+    # Wicked metaprogramming hack to :
+    # - make the new method public to enable initialisation
+    # - add a chart_type attribute to base class
+    def self.inherited(subclass) #:nodoc:
+      subclass.class_eval do
+        attr_reader :chart_type
+        class <<self ; public :new ; end
+      end
+    end
+
+    # Chart width, in pixels
+    attr_accessor :width
+
+    # Chart height, in pixels
+    attr_accessor :height
+
+    # Chart title
+    attr_accessor :title
+
+    # Chart title color (hex value)
+    attr_accessor :title_color
+
+    # Chart title font size
+    attr_accessor :title_font_size
+
+
+    # Encoding
+    attr_accessor :encoding
+
+    # TODO write doc here
+    def initialize(options = {}, &block)
+      @width    = 320
+      @height   = 200
+      @encoding = :simple
+      @data = []
+      @params = {}
+      options.each { |k, v| send("#{k}=", v) }
+      yield self if block_given?
+    end
+
+    def title=(title) #:nodoc:
+      @title = title.gsub("\n", "|")
+    end
+
+    # Sets the chart's width, in pixels. Raises +ArgumentError+
+    # if +width+ is less than 1 or greater than 1,000 (440 for maps).
+    def width=(width)
+      width_max = @chart_type == 't' ? 440 : 1_000
+      if width.nil? || width < 1 || width > width_max
+        raise ArgumentError, "Invalid width: #{width.inspect}"
+      end
+
+      @width = width
+    end
+
+    # Sets the chart's height, in pixels. Raises +ArgumentError+
+    # if +height+ is less than 1 or greater than 1,000 (220 for maps).
+    def height=(height)
+      height_max = @chart_type == 't' ? 220 : 1_000
+      if height.nil? || height < 1 || height > height_max
+        raise ArgumentError, "Invalid height: #{height.inspect}"
+      end
+
+      @height = height
+    end
+
+    # Returns the chart's size as "WIDTHxHEIGHT".
+    def size
+      "#{width}x#{height}"
+    end
+
+    # Sets the chart's size as "WIDTHxHEIGHT". Raises +ArgumentError+
+    # 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
+    end
+
+
+    # Set the data encoding to one of :simple, :text or :extended
+    def encoding=(enc)
+      raise ArgumentError.new("unsupported encoding: #{encoding.inspect}") unless GoogleChart::ENCODINGS.include?(enc)
+      @encoding = enc
+    end
+
+    # Return a hash of the query params that will be converted to the URL
+    def query_params
+      @params.clear
+      add_defaults
+      add_data
+      add_legends if @legends and show_legend?
+      add_labels  if @labels and show_labels?
+      add_colors  if @colors
+      add_fills   if @fills
+      add_axes    if @axes
+      add_grid    if @grid
+      add_markers if @markers
+      add_bar_width_and_spacing if respond_to?(:add_bar_width_and_spacing)
+      add_map_parameters if respond_to?(:add_map_parameters)
+      return @params
+    end
+
+    # Returns a URL to access the chart.
+    # Use +extras+ to add more parameters that may be unsupported or impossible to construct using gchartrb
+    def to_url(extras={})
+      query = query_params.merge(extras).collect { |k, v| "#{k}=#{URI.escape(v)}" }.join("&")
+      "#{GoogleChart::URL}?#{query}"
+    end
+
+    private
+
+    def add_defaults
+      @params[:cht] = chart_type
+      @params[:chs] = size
+      @params[:chtt] = title if title
+      @params[:chts] = [title_color, title_font_size].compact.join(",")
+    end
+
+    def add_data
+      sets = encode_data # calling encode data method of subclass
+      prefix = case encoding
+               when :simple then "s:"
+               when :text then "t:"
+               when :extended then "e:"
+               end
+      @params[:chd] = prefix + sets.join(get_series_separator)
+    end
+
+    def get_series_separator
+      encoding == :text ? "|" : ","
+    end
+
+    def get_data_separator
+      encoding == :text ? "," : ""
+    end
+  end
+end

data/lib/google_chart/line_chart.rb

@@ -0,0 +1,19 @@
+module GoogleChart
+  class LineChart < Base
+    include Legend
+    include Color
+    include DataArray
+    include Fills
+    include Axis
+    include Grid
+    include Markers
+
+    data_type :numeric_array
+
+    def initialize(options={})
+      @chart_type = "lc"
+      @show_legend = false
+      super(options)
+    end
+  end
+end

data/lib/google_chart/linexy_chart.rb

@@ -0,0 +1,20 @@
+module GoogleChart
+  class LineXYChart < Base
+    include Legend
+    include Color
+    include DataArray
+    include Fills
+    include Axis
+    include Grid
+    include Markers
+
+    data_type :numeric_2d_array
+
+
+    def initialize(options={})
+      @chart_type = "lxy"
+      @show_legend = false
+      super(options)
+    end
+  end
+end

data/lib/google_chart/map_chart.rb

@@ -0,0 +1,74 @@
+module GoogleChart
+  class MapChart < Base
+    include Color
+    include DataArray
+    include Fills
+    
+    GEOGRAPHICAL_AREAS = [ :africa, :asia, :europe, :middle_east, :south_america, :usa, :world ]
+    ISO_3166_1_ALPHA_2 = [ :AF, :AX, :AL, :DZ, :AS, :AD, :AO, :AI, :AQ, :AG, :AR, :AM, :AW, :AU, :AT, :AZ, :BS, :BH, :BD, :BB, :BY, :BE, :BZ, :BJ, :BM, :BT, :BO, :BA, :BW, :BV, :BR, :IO, :BN, :BG, :BF, :BI, :KH, :CM, :CA, :CV, :KY, :CF, :TD, :CL, :CN, :CX, :CC, :CO, :KM, :CG, :CD, :CK, :CR, :CI, :HR, :CU, :CY, :CZ, :DK, :DJ, :DM, :DO, :EC, :EG, :SV, :GQ, :ER, :EE, :ET, :FK, :FO, :FJ, :FI, :FR, :GF, :PF, :TF, :GA, :GM, :GE, :DE, :GH, :GI, :GR, :GL, :GD, :GP, :GU, :GT, :GG, :GN, :GW, :GY, :HT, :HM, :VA, :HN, :HK, :HU, :IS, :IN, :ID, :IR, :IQ, :IE, :IM, :IL, :IT, :JM, :JP, :JE, :JO, :KZ, :KE, :KI, :KP, :KR, :KW, :KG, :LA, :LV, :LB, :LS, :LR, :LY, :LI, :LT, :LU, :MO, :MK, :MG, :MW, :MY, :MV, :ML, :MT, :MH, :MQ, :MR, :MU, :YT, :MX, :FM, :MD, :MC, :MN, :ME, :MS, :MA, :MZ, :MM, :NA, :NR, :NP, :NL, :AN, :NC, :NZ, :NI, :NE, :NG, :NU, :NF, :MP, :NO, :OM, :PK, :PW, :PS, :PA, :PG, :PY, :PE, :PH, :PN, :PL, :PT, :PR, :QA, :RE, :RO, :RU, :RW, :BL, :SH, :KN, :LC, :MF, :PM, :VC, :WS, :SM, :ST, :SA, :SN, :RS, :SC, :SL, :SG, :SK, :SI, :SB, :SO, :ZA, :GS, :ES, :LK, :SD, :SR, :SJ, :SZ, :SE, :CH, :SY, :TW, :TJ, :TZ, :TH, :TL, :TG, :TK, :TO, :TT, :TN, :TR, :TM, :TC, :TV, :UG, :UA, :AE, :GB, :US, :UM, :UY, :UZ, :VU, :VE, :VN, :VG, :VI, :WF, :EH, :YE, :ZM, :ZW ]
+    STATE_ABBREVIATIONS = [ :AL, :AK, :AZ, :AR, :CA, :CO, :CT, :DE, :DC, :FL, :GA, :HI, :ID, :IL, :IN, :IA, :KS, :KY, :LA, :ME, :MD, :MA, :MI, :MN, :MS, :MO, :MT, :NE, :NV, :NH, :NJ, :NM, :NY, :NC, :ND, :OH, :OK, :OR, :PA, :RI, :SC, :SD, :TN, :TX, :UT, :VT, :VA, :WA, :WV, :WI, :WY ]
+    
+    attr_accessor :geographical_area, :default_color, :gradient
+
+    data_type :numeric
+
+    def initialize(options={})
+      @chart_type = 't'
+      @show_legend = false
+      @default_color = 'FFFFFF'
+      super(options)
+    end
+
+
+    # Called to add map-specific parameters to the query_params hash.
+    def add_map_parameters
+      @params[:chtm] = geographical_area.to_s
+      @params[:chld] = @region_codes.join('') unless @region_codes.empty?
+      unless @default_color.empty?
+        @params[:chco] = @params[:chco].empty? ? @default_color : "#{@default_color},#{@params[:chco]}"
+      end
+    end
+
+
+    #
+    # ACCESSORS.
+    #
+    def data(code, data)
+      raise ArgumentError.new("data should be an integer value") unless data.is_a?(Numeric)
+      @data << data
+      region_code(code)
+    end
+    
+    def geographical_area=(area)
+      raise ArgumentError.new("area must be one of :#{GEOGRAPHICAL_AREAS.join(', :')}") unless GEOGRAPHICAL_AREAS.include?(area)
+      @geographical_area = area
+    end
+    
+    def gradient=(gradient_colors)
+      if gradient_colors.is_a?(Array)
+        gradient_colors.each { |gradient_color| color(gradient_color) }
+      elsif gradient_colors.is_a?(String)
+        color(gradient_colors)
+      else
+        raise ArgumentError.new("gradient must be a single RGB value as a String or an Array of String RGB values")
+      end
+    end
+    
+    private
+    def region_code(code)
+      @region_codes ||= []
+      
+      # Ensure a proper region code is being added.
+      raise ArgumentError.new("geographical area must be defined before adding data") unless @geographical_area
+      
+      if @geographical_area == :usa
+        raise ArgumentError.new("geographical area must be a US state abbreviation") unless STATE_ABBREVIATIONS.include?(code)
+      else
+        raise ArgumentError.new("geographical area must be an ISO-3166-1 alpha-2 code") unless ISO_3166_1_ALPHA_2.include?(code)
+      end
+      
+      @region_codes << code
+    end
+
+  end
+end

data/lib/google_chart/modules/axis.rb

@@ -0,0 +1,62 @@
+require 'ostruct'
+module GoogleChart
+  # This module is used as a mixin for providing axis
+  module Axis
+    AXIS_TYPE_MAPPING = { :top => "t", :bottom => "x", :left => "y", :right => "r" }
+    ALIGNMENT_MAPPING = { :center => 0, :left => -1, :right => -1}
+
+    Axis = Struct.new("Axis", :type, :labels, :positions, :range, :color, :font_size, :alignment)
+
+    def axis(type, options={})
+      @axes ||= []
+      raise ArgumentError.new("Axis type must be :top, :bottom, :left or :right") unless AXIS_TYPE_MAPPING.keys.include?(type)
+      axis = Axis.new
+      axis.type = type
+
+      options.each { |k,v| axis.send("#{k}=",v) }
+      yield axis if block_given?
+
+      validate_axis(axis)
+      @axes << axis
+    end
+
+    private
+    def add_axes
+      chxt       = @axes.collect { |axis| "#{AXIS_TYPE_MAPPING[axis.type]}" }
+      labels     = @axes.collect { |axis| "#{@axes.index(axis)}:|#{axis.labels.join('|')}" if axis.labels }.compact
+      positions  = @axes.collect { |axis| "#{@axes.index(axis)},#{axis.positions.join(',')}" if axis.positions}.compact
+      ranges     = @axes.collect { |axis| "#{@axes.index(axis)},#{axis.range.min},#{axis.range.max}" if axis.range }.compact
+      styles     = @axes.collect do |axis|
+                     style = [axis.color,axis.font_size, ALIGNMENT_MAPPING[axis.alignment]].compact
+                     unless style.empty?
+                       "#{@axes.index(axis)},#{style.join(',')}"
+                     end
+                   end.compact
+
+      @params[:chxt] = chxt.join(",")
+      @params[:chxl] = labels.join("|") unless labels.empty?
+      @params[:chxp] = positions.join("|") unless positions.empty?
+      @params[:chxr] = ranges.join("|") unless ranges.empty?
+      @params[:chxs] = styles.join("|") unless styles.empty?
+    end
+
+    def validate_axis(axis)
+      raise ArgumentError.new("color must be a string containing a hex value") unless axis.color == nil or axis.color.is_a?(String)
+      raise ArgumentError.new("labels must be an array") unless axis.labels == nil or axis.labels.is_a?(Array)
+      raise ArgumentError.new("positions must be an array of numeric values") unless axis.positions == nil or (axis.positions.is_a?(Array) and axis.positions.is_numeric_array?)
+      raise ArgumentError.new("font_size must be an integer") unless axis.font_size == nil or axis.font_size.is_a?(Integer)
+      raise ArgumentError.new("range must be an range of integer values") unless axis.range == nil or axis.range.is_a?(Range) or axis.range.min.is_a?(Integer)
+      raise ArgumentError.new("font_size cannot be specified without a color") if (axis.font_size && axis.color == nil)
+      raise ArgumentError.new("alignment cannot be specified without a color") if (axis.alignment && (axis.color == nil or axis.font_size == nil))
+      raise ArgumentError.new("alignment must be one of :left, :center, :right") unless (axis.alignment ==nil or ALIGNMENT_MAPPING.keys.include?(axis.alignment))
+
+      unless (axis.labels.to_a.size == axis.positions.to_a.size)
+        raise ArgumentError.new("sizes of labels and positions must be the same") unless axis.labels == nil or axis.positions == nil
+      end
+
+      if axis.positions and axis.range
+        raise ArgumentError.new("positions must be in the specified range") unless axis.positions.all? { |item| axis.range.include?(item)}
+      end
+    end
+  end
+end

data/lib/google_chart/modules/color.rb

@@ -0,0 +1,15 @@
+module GoogleChart
+  # This module is used as a mixin for providing color functionality
+  module Color
+    private
+    def color(color)
+      @colors ||= []
+      @colors << color
+    end
+
+    def add_colors
+      @params[:chco] = @colors.compact.join(",") unless @colors.compact.empty?
+    end
+
+  end
+end

data/lib/google_chart/modules/data_array.rb

@@ -0,0 +1,57 @@
+module GoogleChart
+  # This module is used as a mixin for providing data functionality
+  module DataArray
+    def self.included(mod)#:nodoc:
+      # Extend class methods
+      mod.send(:extend,ClassMethods)
+    end
+
+    def data(legend, series, color = nil)
+      raise ArgumentError.new("Invalid value for series data") unless series.send(self.class.get_data_type)
+      @data << series
+      legend(legend)
+      color(color)
+    end
+
+    def encode_data
+      if @data.first.is_a?(Numeric)
+        max_val = (self.max or @data.max)
+        sets = [@data.collect { |d| GoogleChart::encode(encoding,d,max_val)}.join(get_data_separator)]
+      elsif @data.first.is_numeric_2d_array? # Check if each data is an array of 2d values
+        x_values = @data.collect { |item| item.x_values }
+        y_values = @data.collect { |item| item.y_values }
+
+        x_max_val = (max_x or x_values.flatten.max)
+        y_max_val = (max_y or y_values.flatten.max)
+
+        x_sets = x_values.collect { |set| set.collect{ |d| GoogleChart::encode(encoding,d,x_max_val)}.join(get_data_separator) }
+        y_sets = y_values.collect { |set| set.collect{ |d| GoogleChart::encode(encoding,d,y_max_val)}.join(get_data_separator) }
+
+        sets = x_sets.zip(y_sets).collect { |item| item.join(get_series_separator) }
+      elsif @data.first.is_numeric_array?
+        max_val = (self.max or @data.flatten.max)
+        sets = @data.collect { |set| set.collect{ |d| GoogleChart::encode(encoding,d,max_val)}.join(get_data_separator) }
+      end
+      return sets
+    end
+
+    module ClassMethods
+      def data_type(type) #:nodoc:
+        raise ArgumentError.new("Invalid data type, must be either :numeric, :numeric_array or :numeric_2d_array") unless [:numeric, :numeric_array, :numeric_2d_array].include?(type)
+        # This is the *instance variable* of the *singleton class* ;)
+        @data_type = type
+
+        if @data_type == :numeric_2d_array
+          attr_accessor :max_x, :max_y
+        else
+          attr_accessor :max
+        end
+      end
+
+      def get_data_type #:nodoc:
+        raise ArgumentError.new("Data type not specified") unless @data_type
+        "is_#{@data_type}?".to_sym
+      end
+    end
+  end
+end

data/lib/google_chart/modules/fills.rb

@@ -0,0 +1,102 @@
+require 'ostruct'
+module GoogleChart
+  # This module is used as a mixin for providing solid, linear gradient and stripe fills
+  module Fills
+    FILL_KINDS = [:solid, :gradient, :stripes]
+
+    FILL_TYPES_SOLID = [:background, :chart, :transparent]
+    FILL_TYPES       = [:background, :chart]
+    FILL_TYPE_CODES  = ["bg", "c", "a"]
+
+    SolidFill    = Struct.new("SolidFill", :type, :color)
+    GradientFill = Struct.new("GradientFill", :type, :angle, :colors, :offsets)
+    StripesFill  = Struct.new("StripesFill", :type, :angle, :colors, :widths)
+
+    # TODO add proper docs
+    def fill(type, options = {})
+      @fills ||= []
+      raise ArgumentError.new("Invalid fill type") unless FILL_KINDS.include?(type)
+      f= create_fill(type)
+
+
+      f.type = :background #default
+      options.each { |k,v| f.send("#{k}=",v)}
+
+      yield f if block_given?
+
+      validate_fill(f)
+
+      @fills << parse_fill(f)
+    end
+
+    private
+    def add_fills
+      @params[:chf] = @fills.join("|") unless @fills.empty?
+    end
+
+    def create_fill(type)
+      case type
+      when :solid
+        SolidFill.new
+      when :gradient
+        GradientFill.new
+      when :stripes
+        StripesFill.new
+      end
+    end
+
+    def validate_fill(f)
+      case f
+      when SolidFill
+        validate_solid(f)
+      when GradientFill
+        validate_gradient(f)
+      when StripesFill
+        validate_stripes(f)
+      end
+    end
+
+    def validate_solid(f)
+      raise ArgumentError.new("Invalid fill type value. Must be one of :background, :chart or :transparent") unless FILL_TYPES_SOLID.include?(f.type)
+      raise ArgumentError.new(":color must be a string value") unless f.color.is_a?(String)
+    end
+
+    def validate_gradient(f)
+      raise ArgumentError.new("Invalid fill type value. Must be one of :background, :chart or :transparent") unless FILL_TYPES.include?(f.type)
+      raise ArgumentError.new("angle must be a numeric value") unless f.angle.is_a?(Numeric)
+      #TODO validate color values using regex
+      raise ArgumentError.new(":colors must be an array of strings") unless f.colors.is_a?(Array) and f.colors.all? { |i| i.is_a?(String)}
+      raise ArgumentError.new(":offsets must be an array of numeric values between 0 and 1") unless f.offsets.is_a?(Array) and
+                                                                                                    f.offsets.is_numeric_array? and
+                                                                                                    f.offsets.all? { |i| i>=0 and i<=1 }
+    end
+
+    def validate_stripes(f)
+      raise ArgumentError.new("Invalid fill type value. Must be one of :background, :chart or :transparent") unless FILL_TYPES.include?(f.type)
+      raise ArgumentError.new("angle must be a numeric value") unless f.angle.is_a?(Numeric)
+      #TODO validate color values using regex
+      raise ArgumentError.new(":colors must be an array of strings") unless f.colors.is_a?(Array) and f.colors.all? { |i| i.is_a?(String)}
+      raise ArgumentError.new(":widths must be an array of numeric values between 0 and 1") unless f.widths.is_a?(Array) and
+                                                                                                    f.widths.is_numeric_array? and
+                                                                                                    f.widths.all? { |i| i>=0 and i<=1 }
+    end
+
+    def parse_fill(f)
+      case f
+      when SolidFill
+        "#{map_type(f.type)},s,#{f.color}"
+      when GradientFill
+        colors_offsets = f.colors.zip(f.offsets).collect { |item| item.join(",") }.join(",")
+        "#{map_type(f.type)},lg,#{f.angle},#{colors_offsets}"
+      when StripesFill
+        colors_widths = f.colors.zip(f.widths).collect { |item| item.join(",") }.join(",")
+        "#{map_type(f.type)},ls,#{f.angle},#{colors_widths}"
+      end
+    end
+
+    def map_type(t)
+      i = FILL_TYPES_SOLID.index(t)
+      FILL_TYPE_CODES[i]
+    end
+  end
+end