smart_chart 0.0.1

data/lib/smart_chart/charts/bar.rb

@@ -0,0 +1,20 @@
+module SmartChart
+  class Bar < MultipleDataSetChart
+    include GridLines
+  
+    private # ---------------------------------------------------------------
+    
+    ##
+    # Specify the Google Chart type.
+    #
+    def type
+      "b" +
+        (orientation == :horizontal ? "h" : "v") +
+        (style       == :stacked    ? "s" : "g")
+    end
+    
+    # zero line
+    def chp
+    end
+  end
+end

data/lib/smart_chart/charts/line.rb

@@ -0,0 +1,22 @@
+module SmartChart
+  class Line < MultipleDataSetChart
+    include GridLines
+    
+  
+    private # ---------------------------------------------------------------
+    
+    ##
+    # Specify the Google Chart type.
+    #
+    def type
+      "lc"
+    end
+
+    ##
+    # Array of all possible query string parameters.
+    #
+    def query_string_params
+      super + [:chg]
+    end
+  end
+end

data/lib/smart_chart/charts/map.rb

@@ -0,0 +1,163 @@
+module SmartChart
+  class Map < SingleDataSetChart
+  
+    ##
+    # Array of valid ISO 3166-1-alpha-2 country codes.
+    # Source: http://code.google.com/apis/chart/isocodes.html
+    #
+    def self.country_codes
+      %w[
+        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
+      ]
+    end
+    
+    ##
+    # Array of valid US state codes.
+    # Source: http://code.google.com/apis/chart/statecodes.html
+    #
+    def self.us_state_codes
+      %w[
+        AK AL AR AZ CA CO CT DE FL GA HI IA ID IL IN KS KY LA MA MD ME MI
+        MN MO MS MT NC ND NE NH NJ NM NV NY OH OK OR PA RI SC SD TN TX UT
+        VA VT WA WI WV WY
+      ]
+    end
+    
+    ##
+    # Array of valid map regions.
+    #
+    def self.regions
+      %w[
+        africa
+        asia
+        europe
+        middle_east
+        south_america
+        usa
+        world
+      ]
+    end
+    
+    # region to be depicted (default "world", see Map.regions for choices)
+    attr_accessor :region
+    
+    # color of countries or states with no data (default white)
+    attr_accessor :foreground
+    
+     
+    private # ---------------------------------------------------------------
+    
+    ##
+    # Specify the Google Chart type.
+    #
+    def type
+      "t"
+    end
+    
+    ##
+    # Array of all possible query string parameters.
+    #
+    def query_string_params
+      super + [
+        :chtm,  # region
+        :chld,  # countries/states
+      ]
+    end
+    
+    ##
+    # Map region query string parameter.
+    #
+    def chtm
+      region || "world"
+    end
+    
+    ##
+    # Countries or states to be indicated on the map.
+    #
+    def chld
+      labels.join
+    end
+    
+    ##
+    # Chart color parameter: default ("foreground") plus gradient.
+    #
+    def chco
+      ([foreground || "FFFFFF"] + super.to_a).join(",")
+    end
+    
+    ##
+    # Get the labels (auto-upcase).
+    #
+    def labels
+      super.map{ |i| i.to_s.upcase } unless super.nil?
+    end
+    
+    ##
+    # Array of validations to be run on the chart.
+    #
+    def validations
+      super + [:map_region]
+    end
+
+    ##
+    # Validate the given map region against Google's available options.
+    #
+    def validate_map_region
+      unless region.nil? or Map.regions.include?(region.to_s)
+        raise DataFormatError,
+          "Map region must be one of: #{Map.regions.join(', ')}"
+      end
+    end
+    
+    ##
+    # Make sure colors are valid hex codes.
+    #
+    def validate_colors
+      super
+      validate_color(foreground) if foreground
+    end
+
+    ##
+    # Make sure the given country codes are specified by ISO 3316.
+    #
+    def validate_labels
+      return if labels.nil?
+      # validate states
+      if region.to_s == "usa"
+        invalids = labels - Map.us_state_codes
+        unless invalids.size == 0
+          raise DataFormatError,
+            "Invalid state code(s): #{invalids.join(', ')}"
+        end
+      # validate countries
+      else
+        invalids = labels - Map.country_codes
+        unless invalids.size == 0
+          raise DataFormatError,
+            "Invalid country code(s): #{invalids.join(', ')}"
+        end
+      end
+    end
+
+    ##
+    # Make sure chart dimensions are within Google's 440x220 limit.
+    #
+    def validate_dimensions
+      if width > 440 or height > 220
+        raise DimensionsError,
+          "Map dimensions may not exceed 440x220 pixels"
+      end
+    end
+  end
+end

data/lib/smart_chart/charts/meter.rb

@@ -0,0 +1,13 @@
+module SmartChart
+  class Meter < SingleDataSetChart
+  
+    private # ---------------------------------------------------------------
+    
+    ##
+    # Specify the Google Chart type.
+    #
+    def type
+      "gom"
+    end
+  end
+end

data/lib/smart_chart/charts/pie.rb

@@ -0,0 +1,32 @@
+module SmartChart
+  class Pie < SingleDataSetChart
+  
+    # number of degrees to rotate start of first slice from 12 o'clock
+    attr_accessor :rotate
+    
+    
+    private # ---------------------------------------------------------------
+    
+    ##
+    # Specify the Google Chart type.
+    #
+    def type
+      case style.to_s
+        when "concentric": "pc"
+        when "3d":         "p3"
+        else               "p"
+      end
+    end
+    
+    ##
+    # Rotation. Google expects radians from 3 o'clock.
+    #
+    def chp
+      r = rotate || 0
+      s = SmartChart.decimal_string(
+        ((r - 90) % 360) * Math::PI / 180.0
+      )
+      s == "0" ? nil : s # omit parameter if zero
+    end
+  end
+end

data/lib/smart_chart/charts/qr_code.rb

@@ -0,0 +1,85 @@
+module SmartChart
+  class QRCode < SingleDataSetChart
+  
+    # output encoding
+    # :utf8 (default), :shift_jis, :iso88591
+    attr_accessor :encoding
+    
+    # error correction level
+    # :l (default), :m, :q, or :h
+    attr_accessor :ec_level
+    
+    # chart margin, in rows/columns
+    attr_accessor :margin
+    
+    def self.ec_levels
+      %w[L M Q H]
+    end
+    
+  
+    private # ---------------------------------------------------------------
+    
+    ##
+    # Specify the Google Chart type.
+    #
+    def type
+      "qr"
+    end
+    
+    ##
+    # Array of all possible query string parameters.
+    #
+    def query_string_params
+      [:cht, :chs, :chl, :chld, :choe]
+    end
+    
+    ##
+    # Raise an exception unless the provided data is given as a string and
+    # not too long.
+    #
+    def validate_data_format
+      unless data.is_a?(String)
+        raise DataFormatError, "Barcode data should be given as a string"
+      end
+      ecs = self.class.ec_levels
+      unless ec_level.nil? or ecs.include?(ec_level.to_s.upcase)
+        raise DataFormatError, "Error correction level must be #{ecs.join(', ')}"
+      end
+      #unless data.size <= 4296
+      #  raise DataFormatError, "Barcode data can be at most 4296 characters"
+      #end
+    end
+    
+    ##
+    # Label query string parameter (text to be encoded).
+    #
+    def chl
+      data
+    end
+    
+    ##
+    # Error correction and margins.
+    #
+    def chld
+      # only return non-nil if non-default value given
+      return nil unless (
+        (ec_level and ![:l, "l", "L"].include?(ec_level)) or
+        (margin and margin != 4)
+      )
+      ec = ec_level || "L"
+      m  = margin || 4
+      ec.to_s.upcase + (m != 4 ? "|#{m}" : "")
+    end
+    
+    ##
+    # Output encoding query string parameter.
+    #
+    def choe
+      case encoding
+      when :shift_jis: "Shift_JIS"
+      when :iso88591:  "ISO-8859-1"
+      else             "UTF-8"
+      end
+    end
+  end
+end

data/lib/smart_chart/charts/radar.rb

@@ -0,0 +1,14 @@
+module SmartChart
+  class Radar < MultipleDataSetChart
+    include GridLines
+  
+    private # ---------------------------------------------------------------
+    
+    ##
+    # Specify the Google Chart type.
+    #
+    def type
+      "r" + (style == :filled ? "s" : "")
+    end
+  end
+end

data/lib/smart_chart/charts/scatter.rb

@@ -0,0 +1,21 @@
+module SmartChart
+  class Scatter < MultipleDataSetChart
+    include GridLines
+  
+    private # ---------------------------------------------------------------
+    
+    ##
+    # Specify the Google Chart type.
+    #
+    def type
+      "s"
+    end
+
+    ##
+    # Array of all possible query string parameters.
+    #
+    def query_string_params
+      super + [:chg]
+    end
+  end
+end

data/lib/smart_chart/charts/venn.rb

@@ -0,0 +1,13 @@
+module SmartChart
+  class Venn < SingleDataSetChart
+  
+    private # ---------------------------------------------------------------
+    
+    ##
+    # Specify the Google Chart type.
+    #
+    def type
+      "v"
+    end
+  end
+end

data/lib/smart_chart/data_set.rb

@@ -0,0 +1,15 @@
+module SmartChart
+  class DataSet
+  
+    attr_accessor :values, :style
+    
+    def initialize(values, style)
+      self.values = values
+      self.style = style
+    end
+    
+    def to_s
+      Encoder::Simple.new(values).to_s
+    end
+  end
+end

data/lib/smart_chart/encoder.rb

@@ -0,0 +1,226 @@
+module SmartChart
+  module Encoder
+  
+    ##
+    # Choose the best encoder, instantiate, and return.
+    #
+    def self.encode(data, min = nil, max = nil)
+      Simple.new(data, min, max)
+    end
+    
+    ##
+    # The Base encoder defines a public interface for all Encoders. To create
+    # an actual Encoder, your subclass should implement _only_ these private
+    # methods:
+    # 
+    #   token       # the single character encoding name
+    #   digits      # the "alphabet" of the encoding (array)
+    #   missing     # digit used for missing data
+    #   delimiter   # between data points
+    #   separator   # between data series
+    #
+    class Base
+      
+      attr_accessor :data_sets, :min, :max
+      
+      def initialize(data_sets, min = nil, max = nil)
+        self.data_sets = data_sets
+        self.min       = min || data_sets.flatten.compact.min
+        self.max       = max || data_sets.flatten.compact.max
+      end
+      
+      ##
+      # The data, encoded as a string (eg: "s:e5Gf4").
+      #
+      def to_s
+        token + ":" + encode
+      end
+      
+      
+      private # -------------------------------------------------------------
+      
+      ##
+      # The business end: map arrays of numbers onto a range of characters.
+      # See http://code.google.com/apis/chart/formats.html for specs.
+      #
+      def encode
+        encoded = []
+        data_sets.each_with_index do |set,i|
+          encoded[i] = []
+          set.each do |d|
+            if d.nil?
+              char = missing
+            else
+              if min == max # don't die when only one data point given
+                char = digits.last
+              else
+                n = (d - min).to_f / (max - min).to_f
+                n = (n * (digits.size - 1)).floor
+                char = digits[n]
+              end
+            end
+            encoded[i] << char
+          end
+        end
+        encoded.map{ |set| set.join(delimiter) }.join(separator)
+      end
+      
+      ##
+      # The single-character name of the encoding, as specified in URLs.
+      # All encoders must implement this method.
+      #
+      def token
+        fail
+      end
+      
+      ##
+      # An array of "digits": the encoding's alphabet, in order.
+      # All encoders must implement this method.
+      #
+      def digits
+        fail
+      end
+      
+      ##
+      # String used for missing data point.
+      # All encoders must implement this method.
+      #
+      def missing
+        fail
+      end
+      
+      ##
+      # Data series separator.
+      #
+      def separator
+        fail
+      end
+      
+      ##
+      # Data point delimiter.
+      #
+      def delimiter
+        ""
+      end
+      
+      ##
+      # Array of uppercase letters.
+      #
+      def uppers
+        chars = ["A"]
+        chars << chars.last.succ while chars.size < 26
+        chars
+      end
+      
+      ##
+      # Array of lowercase letters.
+      #
+      def lowers
+        chars = ["a"]
+        chars << chars.last.succ while chars.size < 26
+        chars
+      end
+      
+      ##
+      # Array of numerals.
+      #
+      def numerals
+        chars = ["0"]
+        chars << chars.last.succ while chars.size < 10
+        chars
+      end
+    end
+    
+    
+    ##
+    # Simple encoding (http://code.google.com/apis/chart/formats.html#simple).
+    #
+    class Simple < Base
+      private
+      
+      def token
+        "s"
+      end
+      
+      ##
+      # ABC...XYZabc...xyz0123456789
+      #
+      def digits
+        uppers + lowers + numerals
+      end
+      
+      def missing
+        "_"
+      end
+
+      def separator
+        ","
+      end
+    end
+    
+    
+    ##
+    # Text encoding (http://code.google.com/apis/chart/formats.html#text).
+    #
+    class Text < Base
+      private
+      
+      def token
+        "t"
+      end
+      
+      ##
+      # ABC...XYZabc...xyz0123456789
+      #
+      def digits
+        (0..100).to_a.map{ |i| i.to_s }
+      end
+      
+      def missing
+        "-1"
+      end
+      
+      def separator
+        "|"
+      end
+
+      def delimiter
+        ","
+      end
+    end
+
+
+    ##
+    # Extended encoding (http://code.google.com/apis/chart/formats.html#extended).
+    #
+    class Extended < Base
+      private
+      
+      def token
+        "e"
+      end
+      
+      ##
+      # AA, AB, AC, ..., .8, .9, .-, ..
+      #
+      def digits
+        chars = uppers + lowers + numerals + %w[- .]
+        arr = []
+        chars.each do |c1|
+          chars.each do |c2|
+            arr << c1 + c2
+          end
+        end
+        arr
+      end
+      
+      def missing
+        "__"
+      end
+
+      def separator
+        ","
+      end
+    end
+  end
+end

data/lib/smart_chart/exceptions.rb

@@ -0,0 +1,43 @@
+module SmartChart
+
+  class SmartChartError < StandardError #:nodoc:
+  end
+  
+  class DataFormatError < SmartChartError #:nodoc:
+  end
+  
+  class ColorFormatError < SmartChartError #:nodoc:
+  end
+  
+  class NoAttributeError < SmartChartError #:nodoc:
+    def initialize(chart, param)
+      chart_type = chart.class.to_s.sub(/^SmartChart::/, "")
+      super("The #{chart_type} chart type does not accept the '#{param}' parameter")
+    end
+  end
+
+  
+  # --- validations ---------------------------------------------------------
+
+  class ValidationError < SmartChartError #:nodoc:
+  end
+  
+  class MissingRequiredAttributeError < ValidationError #:nodoc:
+    def initialize(chart, param)
+      chart_type = chart.class.to_s.sub(/^SmartChart::/, "")
+      super("The #{chart_type} chart type requires the '#{param}' parameter")
+    end
+  end
+  
+  class DimensionsError < ValidationError #:nodoc:
+    def initialize(message = nil)
+      super(message || "Chart dimensions must result in at most 300,000 pixels")
+    end
+  end
+  
+  class UrlLengthError < ValidationError #:nodoc:
+    def initialize(message = nil)
+      super(message || "URL too long (must not exceed #{SmartChart::URL_MAX_LENGTH} characters)")
+    end
+  end
+end

data/lib/smart_chart/features/axis_lines.rb

@@ -0,0 +1,29 @@
+module SmartChart
+  module AxisLines
+
+    def self.included(base)
+      base.class_eval do
+        attr_accessor :axis
+      end
+    end
+
+
+    private # ---------------------------------------------------------------
+  
+    ##
+    # Axis type parameter.
+    #
+    def chxt
+      #return nil unless (axis.is_a?(Hash) and (axis[:sides].is_a?(Array))
+      "TODO"
+    end
+
+    ##
+    # Axis style parameter.
+    #
+    def chxs
+      #return nil unless (axis.is_a?(Hash) and (axis[:color] or axis[:style]))
+      "TODO"
+    end
+  end  
+end