smart_chart 0.0.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Alex Reisner
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,187 @@
+= SmartChart
+
+SmartChart is an easy way to render charts on web pages. It uses the Google Charts engine so there are no server-side dependencies or performance issues--just install and go.
+
+<b>SmartChart is still in the early stages of development. Only maps, barcodes, and line charts (partially) are working at all. However, much of the interface is described below (plus to-do list) and if you'd like to contribute, please do.</b>
+
+
+== Key Benefits
+
+<b>1. Designed as a chart-making interface, not as a Google Charts wrapper.</b> Other APIs effectively just give Google Chart parameters different names, leading you to wonder: why am I learning an API to an API? SmartChart is an intelligent chart-authoring syntax that happens to use Google Charts as a back-end. It may support other charting engines in the future.
+
+<b>2. Place chart elements with respect to data points, not chart size.</b> If you want horizontal axis lines on your graph every 10 units (along the Y-axis) you simply specify this. If you've worked much with the native Google Charts interface you know you have to do several calculations to get this to work, and any library that simply "wraps" Google Charts suffers from this same annoyance.
+
+<b>3. You get useful feedback when you do something wrong.</b> If you specify more data points than Google can handle, you get an error message. If you specify a bigger chart than Google will serve, you get an error message. Forget to specify a required parameter? That's an error message too. The thing is, with the raw Google Charts interface you get no useful feedback in any of these cases, which can lead to _very_ long and frustrating debugging sessions.
+
+<b>4. The best data encoding is selected automatically.</b> SmartChart examines your data and selects the optimal way to encode your data to keep HTTP requests short while preserving granularity. There's no way a chart author should have to think about Google's data encoding methods. Forget I even mentioned it.
+
+
+== Examples
+
+  SmartChart::Line.new(
+
+    # y-axis range
+    :y_min  => -40,
+    :y_max  => 80,
+
+    # data (specify line/bar styles with data)
+    :data => [
+      {
+        :values    => [1,2,3,4],
+        :label     => "Profit",
+        :thickness => 2,
+        :color     => '550055',
+        :style     => {:solid => 3, :blank => 2}
+      },
+      {
+        :values    => [2,4,6,8],
+        :label     => "Reputation",
+        :thickness => 2,
+        :color     => 'AABBCC',
+        :style     => :dotted
+      }
+    ],
+    
+    # axis lines
+    :axis => {
+      :sides => [:left, :right, :bottom],     # empty array for none
+      :color => 'DDDDDD',
+      :style => :dashed
+    }
+    
+    # grid lines
+    :grid => {
+      :x     => {:every => 10, :offset => 2}, # based on number of data points
+      :y     => {:every => 5},                # based on numeric data range
+      :style => :dashed                       # no :color or :thickness
+    },
+    
+    # labels
+    :x_labels => {
+      1  => "Jan",
+      4  => "Apr",
+      7  => "Jul",
+      10 => "Oct"
+    }
+    
+    # options for HTML tag
+    :html => {
+      :id    => "stock_graph",
+      :class => "graph"
+    }
+  )
+  
+  SmartChart::Pie.new(
+    :style  => "3d",
+    :rotate => 45,   # degrees from vertical (start of first slice)
+    ...
+  )
+
+  # display
+  g = SmartChart::Line.new(...)
+  g.to_url
+  g.to_html
+  
+  # QR Code
+  g = SmartChart::QRCode.new(:data => "some data").to_s
+
+
+== Specifying Data
+
+Data is specified in slightly different ways for different charts. In the simplest case, a QR code (<tt>SmartChart::QRCode</tt>), the data is simply a string:
+
+  chart.data = "A sentence full of data."
+
+Another simple case is a map (<tt>SmartChart::Map</tt>), where data is specified as a hash of region-value pairs:
+
+  chart.data = {
+    :US => 74,
+    :CA => 81,
+    :MX => 52,
+    :RU => 19,
+    :AU => 41
+  }
+
+Data can be passed to pie charts in a similar way. For more complex graphs depicting multiple series, data and other information about each series is given as a hash (in an array if there is more than one), for example for a line graph:
+
+  chart.data = [
+    {
+      :values    => [23, 26, 46, 52, 51, 78],
+      :label     => "Stock price",
+      :thickness => 2,
+      :color     => '0099FF'
+    },
+    {
+      :values    => [65, 64, 58, 52, 63, 79],
+      :label     => "Consumer interest",
+      :thickness => 1,
+      :color     => 'FF0099',
+      :style     => :dotted
+      }
+    }
+  ]
+
+
+== Axis Lines
+
+Actual output is limited by Google's requirements. For example, while Google provides for a line chart with no axis lines ("sparkline"), there is no analogous bar chart type. However, SmartChart will simulate this for you by cropping the chart image using a <div> when you call the chart.to_html method.
+
+
+== To-do List
+
+* query_string_params should be a class variable so feature modules can
+  auto-add their parameters
+
+* validations
+  * margins and legend dimensions are integers
+  * grid line attributes
+  
+* grids
+  * easy placement of y-gridline at zero, if exists
+  * easy placement of gridlines at label positions
+
+* axis lines
+  * specify which ones to print
+  * hide all ("sparklines")
+  * hide bar graph axes by hiding 1px from left and bottom of image when to_html is called
+  * chxr parameter?
+
+* labels
+  * on line, scatter, bar graphs
+  * labels on other axes (top and right)
+  * multiple rows of labels on same axis
+
+* legend
+  * size, position
+  * inline legends (line up with ends of lines -- see http://code.google.com/p/graphy/wiki/UserGuide)
+
+* general
+  * support advanced background ("fill") options like gradients
+
+* markers
+  * note: invisible data series available for marker positioning
+    see: http://code.google.com/apis/chart/formats.html#multiple_data_series
+
+* SingleDataSetChart
+  * document attributes
+
+* QRCode
+  * data length validation for given EC level and character type
+    * see table: http://code.google.com/apis/chart/types.html#qrcodes
+    * may be irrelevant because URL_MAX_LENGTH == 2074
+
+* data and encoding
+  * The best encoding type should be selected automatically (whatever is shortest with enough granularity). Avoid URLs longer than 2074 characters. Default to Extended, but use Simple if (1) URL would be too long, (2) image is less than 100px tall, or (3) not enough data point to justify it.
+  * data granularity adjustment (curve smoothing, rolling average?)
+    * see bottom: http://code.google.com/apis/chart/formats.html
+    * at least 1 pixel per data point
+
+
+
+== References
+
+Other Google Charts APIs:
+http://groups.google.com/group/google-chart-api/web/useful-links-to-api-libraries
+
+
+Copyright (c) 2009 Alex Reisner. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,56 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name        = "smart_chart"
+    gem.summary     = %Q{Easily create charts and graphs for the web (uses Google Charts).}
+    gem.description = %Q{Easily create charts and graphs for the web (uses Google Charts).}
+    gem.email       = "alex@alexreisner.com"
+    gem.homepage    = "http://github.com/alexreisner/smart_chart"
+    gem.authors = ["Alex Reisner"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "SmartChart #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/smart_chart/base_chart.rb

@@ -0,0 +1,428 @@
+module SmartChart
+  
+  ##
+  # Maximum length of URL accepted by Google.
+  #
+  URL_MAX_LENGTH = 2074
+
+  ##
+  # Takes a decimal number and returns a string with up to +frac+
+  # digits to the right of the '.'.
+  #
+  def self.decimal_string(num, frac = 3)
+    str = "%.#{frac}f" % num
+    str = str[0...-1] while str[-1,1] == "0"
+    str = str[0...-1] if str[-1,1] == "." # leave zeros left of .
+    str
+  end
+  
+  ##
+  # Method names are called attributes, data for URL are called parameters.
+  # Use attr_writers for all attributes, and wrte readers so
+  # they instantiate the correct object type.
+  #
+  class BaseChart
+    
+    # dimensions of chart image, in pixels
+    attr_accessor :width, :height
+    
+    # chart data
+    attr_accessor :data
+    
+    # chart range
+    attr_accessor :y_min, :y_max
+    
+    # chart background
+    attr_accessor :background
+    
+    # chart margins
+    attr_accessor :margins
+
+    # legend properties
+    attr_accessor :legend
+
+    # bar chart orientation -- :vertical (default) or :horizontal
+    # pie chart orientation -- degrees of rotation
+    attr_accessor :orientation
+    
+    # bar   -- :grouped (default) or :stacked
+    # pie   -- nil (2D, default), "3d", or :concentric
+    # radar -- nil (default) or :filled
+    attr_accessor :style
+    
+    ##
+    # Accept attributes and attempt to assign each to an attribute.
+    #
+    def initialize(options = {})
+      options.each do |k,v|
+        begin
+          send("#{k}=", v)
+        rescue NoMethodError
+          raise NoAttributeError.new(self, k)
+        end
+      end
+    end
+    
+    ##
+    # Get the chart URL query string.
+    #
+    def to_query_string(encode = true, validation = true)
+      validate if validation
+      query_string(encode)
+    end
+    
+    ##
+    # Get the full chart URL.
+    #
+    def to_url(encode = true, validation = true)
+      "http://chart.apis.google.com/chart?" +
+        to_query_string(encode, validation)
+    end
+    
+    ##
+    # Chart as an HTML tag.
+    #
+    def to_html(encode = true, validation = true)
+      '<img src="%s" />' % to_url(encode, validation)
+    end
+    
+    ##
+    # Run validation (may raise exceptions).
+    #
+    def validate!
+      validate
+    end
+    
+    ##
+    # Does the chart pass all validations?
+    #
+    def valid?
+      begin
+        validate
+        true
+      rescue ValidationError
+        false
+      end
+    end
+    
+    
+    private # ---------------------------------------------------------------
+    
+    ##
+    # Chart type URL parameter, for example:
+    # 
+    #   :bvs  # vertical bar
+    #   :p    # pie
+    #   :p3   # 3D pie
+    # 
+    # All subclasses *must* implement this method.
+    #
+    def type
+      fail
+    end
+    
+    ##
+    # Get an array of values to be graphed.
+    # Subclasses *must* implement this method.
+    #
+    def data_values
+      fail 
+    end
+    
+    ##
+    # The number of data points represented along the x-axis.
+    #
+    def data_values_count
+      data_values.map{ |set| set.size }.max
+    end
+    
+    ##
+    # Get the minimum Y-value for the chart (from data or explicitly set).
+    #
+    def y_min
+      @y_min || data_values.flatten.compact.min
+    end
+    
+    ##
+    # Get the maximum Y-value for the chart (from data or explicitly set).
+    #
+    def y_max
+      @y_max || data_values.flatten.compact.max
+    end
+    
+    ##
+    # Array of names of required attributes.
+    #
+    def required_attrs
+      [
+        :width,
+        :height,
+        :data
+      ]
+    end
+    
+    ##
+    # Array of validations to be run on the chart.
+    #
+    def validations
+      [
+        :required_attrs,
+        :dimensions,
+        :data_format,
+        :labels,
+        :colors,
+        :url_length
+      ]
+    end
+    
+    ##
+    # Make sure chart dimensions are within Google's 300,000 pixel limit.
+    #
+    def validate_dimensions
+      raise DimensionsError unless width * height <= 300000
+    end
+    
+    ##
+    # Validate data format.
+    # Subclasses *must* implement this method.
+    #
+    def validate_data_format
+      fail
+    end
+    
+    ##
+    # Make sure labels are specified in proper format
+    # Subclasses *must* implement this method.
+    #
+    def validate_labels
+    end
+    
+    ##
+    # Make sure colors are valid hex codes.
+    # Subclasses should probably implement this method.
+    #
+    def validate_colors
+      validate_color(background) 
+    end
+    
+    
+    # --- subclasses should not overwrite anything below this line ----------
+    
+    ##
+    # The query string for the chart.
+    #
+    def query_string(encode = true)
+      values = query_string_params.map{ |p| format_param(p, encode) }
+      values.compact.join("&")
+    end
+    
+    ##
+    # Format a query string parameter for a URL (string: name=value). Uses
+    # %-encoding unless second argument is false.
+    #
+    def format_param(name, encode = true)
+      unless (value = send(name).to_s) == ""
+        value = CGI.escape(value) if encode
+        name.to_s + '=' + value
+      end
+    end
+    
+    ##
+    # Is the data given as a single bare array of values?
+    #
+    def bare_data_set?
+      data.is_a?(Array) and ![Array, Hash].include?(data.first.class)
+    end
+
+    ##
+    # Run all validations on the chart attributes.
+    #
+    def validate
+      validations.each{ |v| send "validate_#{v}" }
+    end
+    
+    ##
+    # Make sure all required chart attributes are specified.
+    #
+    def validate_required_attrs
+      required_attrs.each do |param|
+        if send(param).nil?
+          raise MissingRequiredAttributeError.new(self, param)
+        end
+      end
+    end
+    
+    ##
+    # Make sure encoded URL is no longer than the maximum allowed length.
+    #
+    def validate_url_length
+      raise UrlLengthError unless to_url(true, false).size <= URL_MAX_LENGTH
+    end
+    
+    ##
+    # Validate a single color (this is not a normal validator).
+    #
+    def validate_color(c)
+      raise ColorFormatError unless (c.nil? or c.match(/^[0-9A-Fa-f]{6}$/))
+    end
+    
+    
+    # --- URL parameter list and methods ------------------------------------
+    
+    ##
+    # Array of names of all possible query string parameters in the order
+    # in which they are output (for easier testing).
+    #
+    def query_string_params
+      [
+        :cht,   # type
+        :chs,   # size
+        :chd,   # data
+        
+        :chco,  # color
+        :chf,   # fill
+        
+        :chl,   # labels
+        :chxt,  # axis_type
+        :chxs,  # axis_style
+        :chxl,  # axis_labels
+        :chxp,  # axis_label_positions
+        :chxr,  # axis_range
+        :chma,  # margins
+        
+        :chbh,  # bar_spacing
+        :chp,   # bar_chart_zero_line, pie chart rotation
+
+        :chm,   # markers
+
+        :chtt,  # title
+        :chdl,  # legend
+        :chdlp, # legend_position
+        
+        :chds   # data_scaling -- never used
+      ]
+    end
+
+    #
+    # All parameter methods should return a string, or an object that 
+    # renders itself as a string via the to_s method.
+    #
+
+    # cht
+    def cht
+      type
+    end
+    
+    # chs
+    def chs
+      "#{width}x#{height}"
+    end
+    
+    # chd
+    def chd
+      Encoder.encode(data_values, y_min, y_max)
+    end
+    
+    # chco
+    def chco
+      data.map{ |d|
+        if d.is_a?(Hash) and c = d[:color]
+          c = [c] unless c.is_a?(Array)
+          c.join('|') # data point delimiter
+        end
+      }.compact.join(',') # data set delimiter
+    end
+    
+    # chf
+    def chf
+      "bg,s,#{background}" if background
+    end
+
+    # chl
+    def chl
+      nil
+    end
+    
+    # chxt
+    def chxt
+      nil
+    end
+
+    # chxl
+    def chxl
+      nil
+    end
+
+    # chxp
+    def chxp
+      nil
+    end
+
+    # chxr
+    def chxr
+      nil
+    end
+
+    # chxs
+    def chxs
+      nil
+    end
+
+    ##
+    # Are legend dimensions specified?
+    #
+    def legend_dimensions_given?
+      legend.is_a?(Hash) and (legend[:width] or legend[:height])
+    end
+
+    # chma
+    def chma
+      return nil unless (margins or legend_dimensions_given?)
+      value = ""
+      if margins.is_a?(Hash)
+        pixels = [:left, :right, :top, :bottom].map{ |i| margins[i] || 0 }
+        value << pixels.join(',')
+      end
+      if legend_dimensions_given?
+        value << "0,0,0,0" if value == ""
+        value << "|#{legend[:width] || 0},#{legend[:height] || 0}"
+      end
+      value
+    end
+
+    # chbh
+    def chbh
+      nil
+    end
+
+    # chp
+    def chp
+      nil
+    end
+
+    # chm
+    def chm
+      nil
+    end
+
+    # chtt
+    def chtt
+      nil
+    end
+
+    # chdl
+    def chdl
+      nil
+    end
+
+    # chdlp
+    def chdlp
+      nil
+    end
+
+    # chds -- never used
+    def chds          
+      nil
+    end
+  end
+end