willbryant-scruffy 0.2.16

data/lib/scruffy/graph.rb

@@ -0,0 +1,205 @@
+require 'forwardable'
+  
+module Scruffy
+  
+  # ==Scruffy Graphs
+  #
+  # Author:: Brasten Sager
+  # Date:: August 5th, 2006
+  #
+  #
+  # ====Graphs vs. Layers (Graph Types)
+  #
+  # Scruffy::Graph is the primary class you will use to generate your graphs.  A Graph does not
+  # define a graph type nor does it directly hold any data.  Instead, a Graph object can be thought
+  # of as a canvas on which other graphs are draw.  (The actual graphs themselves are subclasses of Scruffy::Layers::Base)
+  # Despite the technical distinction, we will refer to Scruffy::Graph objects as 'graphs' and Scruffy::Layers as
+  # 'layers' or 'graph types.'
+  #
+  #
+  # ==== Creating a Graph
+  #
+  # You can begin building a graph by instantiating a Graph object and optionally passing a hash
+  # of properties.
+  #
+  #   graph = Scruffy::Graph.new
+  #
+  #   OR
+  #
+  #   graph = Scruffy::Graph.new(:title => "Monthly Profits", :theme => Scruffy::Themes::RubyBlog.new)
+  #
+  # Once you have a Graph object, you can set any Graph-level properties (title, theme, etc), or begin adding
+  # graph layers.  You can add a graph layer to a graph by using the Graph#add or Graph#<< methods.  The two
+  # methods are identical and used to accommodate syntax preferences.
+  #
+  #   graph.add(:line, 'John', [100, -20, 30, 60])
+  #   graph.add(:line, 'Sara', [120, 50, -80, 20])
+  #
+  #   OR
+  #
+  #   graph << Scruffy::Layers::Line.new(:title => 'John', :points => [100, -20, 30, 60])
+  #   graph << Scruffy::Layers::Line.new(:title => 'Sara', :points => [120, 50, -80, 20])  
+  #
+  # Now that we've created our graph and added a layer to it, we're ready to render!  You can render the graph
+  # directly to SVG or any other image format (supported by RMagick) with the Graph#render method:
+  #
+  #   graph.render    # Renders a 600x400 SVG graph
+  #
+  #   OR
+  #
+  #   graph.render(:width => 1200)
+  #
+  #   # For image formats other than SVG:
+  #   graph.render(:width => 1200, :as => 'PNG')
+  #
+  #   # To render directly to a file:
+  #   graph.render(:width => 5000, :to => '<filename>')
+  #
+  #   graph.render(:width => 700, :as => 'PNG', :to => '<filename>')
+  #
+  # And that's your basic Scruffy graph!  Please check the documentation for the various methods and
+  # classes you'll be using, as there are a bunch of options not demonstrated here.
+  #
+  # A couple final things worth noting:
+  # * You can call Graph#render as often as you wish with different rendering options.  In
+  #   fact, you can modify the graph any way you wish between renders.
+  #
+  #
+  # * There are no restrictions to the combination of graph layers you can add.  It is perfectly
+  #   valid to do something like:
+  #     graph.add(:line, [100, 200, 300])
+  #     graph.add(:bar, [200, 150, 150])
+  #
+  #   Of course, while you may be able to combine some things such as pie charts and line graphs, that
+  #   doesn't necessarily mean they will make any logical sense together.  We leave those decisions up to you. :)
+
+  class Graph
+    extend Forwardable;
+    
+    include Scruffy::Helpers::LayerContainer
+
+    # Delegating these getters to the internal state object.
+    def_delegators  :internal_state, :title,:x_legend,:y_legend, :theme, :default_type, 
+                    :point_markers,:point_markers_rotation,:point_markers_ticks, :value_formatter, :rasterizer,
+                    :key_formatter
+                  
+    def_delegators  :internal_state, :title=, :theme=,:x_legend=,:y_legend=, :default_type=,
+                    :point_markers=,:point_markers_rotation=,:point_markers_ticks=, :value_formatter=, :rasterizer=,
+                    :key_formatter=
+    
+    attr_reader :renderer     # Writer defined below
+    
+    # Returns a new Graph.  You can optionally pass in a default graph type and an options hash.
+    #
+    #   Graph.new           # New graph
+    #   Graph.new(:line)    # New graph with default graph type of Line
+    #   Graph.new({...})    # New graph with options.
+    #
+    # Options:
+    #
+    # title::  Graph's title
+    # x_legend :: Title for X Axis
+    # y_legend :: Title for Y Axis
+    # theme::  A theme object to use when rendering graph
+    # layers::  An array of Layers for this graph to use
+    # default_type::  A symbol indicating the default type of Layer for this graph
+    # value_formatter::   Sets a formatter used to modify marker values prior to rendering
+    # point_markers::  Sets the x-axis marker values
+    # point_markers_rotation::  Sets the angle of rotation for x-axis marker values
+    # point_markers_ticks::  Sets a small tick mark above each marker value.  Helful when used with rotation.    
+    # rasterizer::  Sets the rasterizer to use when rendering to an image format.  Defaults to RMagick.
+    def initialize(*args)
+      self.default_type   = args.shift if args.first.is_a?(Symbol)
+      options             = args.shift.dup if args.first.is_a?(Hash)
+      raise ArgumentError, "The arguments provided are not supported." if args.size > 0
+
+      options ||= {}
+      
+      
+      self.theme = Scruffy::Themes::Standard.new
+      self.renderer = Scruffy::Renderers::Standard.new
+      self.rasterizer = Scruffy::Rasterizers::RMagickRasterizer.new
+      self.value_formatter = Scruffy::Formatters::Number.new
+      self.key_formatter = Scruffy::Formatters::Number.new
+
+      %w(title x_legend y_legend theme layers default_type value_formatter point_markers point_markers_rotation point_markers_ticks rasterizer key_formatter).each do |arg|
+        self.send("#{arg}=".to_sym, options.delete(arg.to_sym)) unless options[arg.to_sym].nil?
+      end
+      
+      raise ArgumentError, "Some options provided are not supported: #{options.keys.join(' ')}." if options.size > 0
+    end
+    
+    # Renders the graph in it's current state to an SVG object.
+    #
+    # Options:
+    # size:: An array indicating the size you wish to render the graph.  ( [x, y] )
+    # width:: The width of the rendered graph.  A height is calculated at 3/4th of the width.
+    # theme:: Theme used to render graph for this render only.
+    # min_value:: Overrides the calculated minimum value used for the graph.
+    # max_value:: Overrides the calculated maximum value used for the graph.
+    # renderer:: Provide a Renderer object to use instead of the default. 
+    #
+    # For other image formats:
+    # as:: File format to render to ('PNG', 'JPG', etc)
+    # to:: Name of file to save graph to, if desired.  If not provided, image is returned as blob/string.
+    def render(options = {})
+      options[:theme]               ||= theme
+      options[:value_formatter]     ||= value_formatter
+      options[:key_formatter]       ||= key_formatter
+      options[:point_markers]       ||= point_markers
+      options[:point_markers_rotation]       ||= point_markers_rotation
+      options[:point_markers_ticks]       ||= point_markers_ticks
+      options[:size]                ||= (options[:width] ? [options[:width], (options.delete(:width) * 0.6).to_i] : [600, 360])
+      options[:title]               ||= title
+      options[:x_legend]               ||= x_legend
+      options[:y_legend]               ||= y_legend
+      options[:layers]              ||= layers
+      options[:min_value]           ||= bottom_value(options[:padding] ? options[:padding] : nil)
+      options[:max_value]           ||= top_value(options[:padding] ? options[:padding] : nil)
+      options[:min_key]             ||= bottom_key
+      options[:max_key]             ||= top_key
+      options[:graph]               ||= self
+
+      # Removed for now.
+      # Added for making smaller fonts more legible, but may not be needed after all.
+      #
+      # if options[:as] && (options[:size][0] <= 300 || options[:size][1] <= 200)
+      #   options[:actual_size] = options[:size]
+      #   options[:size] = [800, (800.to_f * (options[:actual_size][1].to_f / options[:actual_size][0].to_f))]
+      # end
+      
+      svg = ( options[:renderer].nil? ? self.renderer.render( options ) : options[:renderer].render( options ) )
+      
+      # SVG to file.
+      if options[:to] && options[:as].nil?
+        File.open(options[:to], 'w') { |file|
+          file.write(svg)
+        }
+      end
+      
+      options[:as] ? rasterizer.rasterize(svg, options) : svg
+    end
+    
+    def renderer=(val)
+      raise ArgumentError, "Renderer must include a #render(options) method." unless (val.respond_to?(:render) && val.method(:render).arity.abs > 0)
+      
+      @renderer = val
+    end
+    
+    alias :layout :renderer
+    
+    def component(id)
+      renderer.component(id)
+    end
+    
+    def remove(id)
+      renderer.remove(id)
+    end
+    
+    private
+      def internal_state
+        @internal_state ||= GraphState.new
+      end
+      
+  end
+end

data/lib/scruffy/graph_state.rb

@@ -0,0 +1,29 @@
+# ===GraphState
+#
+# Author:: Brasten Sager
+# Date:: September 27th, 2007
+#
+# State object for holding all of the graph's
+# settings.  Attempting to clean up the
+# graph interface a bit.
+
+module Scruffy
+  class GraphState
+
+    attr_accessor :title
+    attr_accessor :x_legend
+    attr_accessor :y_legend
+    attr_accessor :theme
+    attr_accessor :default_type
+    attr_accessor :point_markers
+    attr_accessor :point_markers_rotation
+    attr_accessor :point_markers_ticks
+    attr_accessor :value_formatter
+    attr_accessor :key_formatter
+    attr_accessor :rasterizer
+    
+    def initialize
+      
+    end
+  end
+end

data/lib/scruffy/helpers.rb

@@ -0,0 +1,13 @@
+# ==Scruffy Helpers
+#
+# Author:: Brasten Sager
+# Date:: August 16th, 2006
+#
+# Modules which provide helper methods for various situations.
+module Scruffy::Helpers; end
+
+require 'scruffy/helpers/canvas'
+require 'scruffy/helpers/layer_container'
+require 'scruffy/helpers/point_container'
+require 'scruffy/helpers/marker_helper'
+#require 'scruffy/helpers/meta'

data/lib/scruffy/helpers/canvas.rb

@@ -0,0 +1,41 @@
+module Scruffy::Helpers
+  
+  # ==Scruffy::Helpers::Canvas
+  # 
+  # Author:: Brasten Sager
+  # Date:: August 16th, 2006
+  # 
+  # Provides common methods for canvas objects.  Primarily used for providing
+  # spacial-type calculations where necessary.
+  module Canvas
+    attr_accessor :components
+    
+    def reset_settings!
+      self.options = {}
+    end
+    
+    def component(id, components=self.components)
+      components.find {|elem| elem.id == id}
+    end
+    
+    def remove(id, components=self.components)
+      components.delete(component(id))
+    end
+    
+    protected
+    # Converts percentage values into actual pixel values based on the known
+    # render size.
+    # 
+    # Returns a hash consisting of :x, :y, :width, and :height elements.
+    def bounds_for(canvas_size, position, size)
+      return nil if (position.nil? || size.nil?)
+      bounds = {}
+      bounds[:x] = canvas_size.first * (position.first / 100.to_f)
+      bounds[:y] = canvas_size.last  * (position.last  / 100.to_f)
+      bounds[:width] = canvas_size.first * (size.first / 100.to_f)
+      bounds[:height] = canvas_size.last * (size.last  / 100.to_f)
+      bounds
+    end
+  end # canvas
+  
+end # scruffy::helpers

data/lib/scruffy/helpers/layer_container.rb

@@ -0,0 +1,119 @@
+module Scruffy::Helpers
+  
+  # ==Scruffy::Helpers::LayerContainer
+  #
+  # Author:: Brasten Sager
+  # Date:: August 16th, 2006
+  #
+  # Adds some common functionality to any object which needs to act as a
+  # container for graph layers.  The best example of this is the Scruffy::Graph
+  # object itself, but this module is also used by Scruffy::Layer::Stacked.
+  module LayerContainer
+    
+    # Adds a Layer to the Graph/Container.  Accepts either a list of 
+    # arguments used to build a new layer, or a Scruffy::Layers::Base-derived 
+    # object.  When passing a list of arguments, all arguments are optional, 
+    # but the arguments specified must be provided in a particular order: 
+    # type (Symbol), title (String), points (Array), options (Hash).
+    #
+    # Both #add and #<< can be used.
+    #
+    #   graph.add(:line, [100, 200, 150])     # Create and add an untitled line graph
+    #
+    #   graph << (:line, "John's Sales", [150, 100])    # Create and add a titled line graph
+    #
+    #   graph << Scruffy::Layers::Bar.new({...})   # Adds Bar layer to graph
+    #
+    def <<(*args, &block)
+      if args[0].kind_of?(Scruffy::Layers::Base)
+        layers << args[0]
+      else
+        type = args.first.is_a?(Symbol) ? args.shift : @default_type
+        title = args.shift if args.first.is_a?(String)
+        
+        # Layer handles PointContainer mixin, don't do it here
+        points = [Array, Hash].include?(args.first.class) ? args.shift : []
+        options = args.first.is_a?(Hash) ? args.shift : {}
+        
+        title ||= ''
+        
+        raise ArgumentError, 
+                'You must specify a graph type (:area, :bar, :line, etc) if you do not have a default type specified.' if type.nil?
+              
+        class_name = "Scruffy::Layers::#{to_camelcase(type.to_s)}"
+        layer_class = Kernel::module_eval(class_name)
+        options = {:points => points, :title => title}.merge options
+        layer = layer_class.new(options, &block)
+        layers << layer
+      end
+      layer
+    end
+    
+    alias :add :<<
+    
+
+    # Layer Writer
+    def layers=(val)
+      @layers = val
+    end
+    
+    # Layer Reader
+    def layers
+      @layers ||= []
+    end
+    
+    # Returns the highest value in any of this container's layers.
+    #
+    # If padding is set to :padded, a 15% padding is added to the highest value.
+    def top_value(padding=nil) # :nodoc:
+      topval = layers.inject(0) { |max, layer| (max = ((max < layer.top_value) ? layer.top_value : max)) unless layer.top_value.nil?; max }
+      below_zero = (topval <= 0)
+      topval = padding == :padded ? (topval + ((topval - bottom_value) * 0.15)) : topval
+      (below_zero && topval > 0) ? 0 : topval
+    end
+  
+    # Returns the lowest value in any of this container's layers.
+    #
+    # If padding is set to :padded, a 15% padding is added below the lowest value.
+    # If the lowest value is greater than zero, then the padding will not cross the zero line, preventing
+    # negative values from being introduced into the graph purely due to padding.
+    def bottom_value(padding=nil) # :nodoc:
+      botval = layers.inject(0) do |min, layer| 
+        (min = ((min > layer.bottom_value) ? layer.bottom_value : min)) unless layer.bottom_value.nil?
+        min 
+      end
+      above_zero = (botval >= 0)
+      botval = (botval - ((top_value - botval) * 0.15)) if padding == :padded
+    
+      # Don't introduce negative values solely due to padding.
+      # A user-provided value must be negative before padding will extend into negative values.
+      (above_zero && botval < 0) ? 0 : botval
+    end
+
+    def bottom_key(padding=nil)
+      return 0 unless layers.any?
+      min = layers[0].bottom_key
+      layers.each do |layer|
+        min = layer.bottom_key if min.nil? && !layer.bottom_key.nil?
+        (min = ((min > layer.bottom_key) ? layer.bottom_key : min)) unless layer.bottom_key.nil?
+      end
+      min
+    end
+    
+    def top_key(padding=nil)
+      return 1 unless layers.any?
+      max = layers[0].top_key
+      layers.each do |layer|
+        max = layer.top_key if max.nil? && !layer.top_key.nil?
+        (max = ((max < layer.top_key) ? layer.top_key : max)) unless layer.top_key.nil?
+      end
+      max
+    end
+
+    protected
+      def to_camelcase(type)  # :nodoc:
+        type.split('_').map { |e| e.capitalize }.join('')
+      end
+
+  end
+end

data/lib/scruffy/helpers/marker_helper.rb

@@ -0,0 +1,25 @@
+module Scruffy::Helpers
+  
+  module Marker
+    
+    def each_marker(markers, min, max, width, options, format_key)
+       all_values = []
+
+      (0...markers).each do |idx|
+        percent = idx.to_f / (markers-1)
+        all_values << min + (max - min) * percent
+      end
+
+      all_values.size.times do |idx|
+        dx = width/(markers - 1)
+        
+        location = idx.to_f * dx #+ dx/2
+        marker_value = all_values[idx]
+        marker_value = options[format_key].route_format(marker_value, idx, options.merge({:all_values => all_values})) if options[format_key]
+
+        yield marker_value, location
+      end  
+
+    end
+  end
+end

data/lib/scruffy/helpers/meta.rb

@@ -0,0 +1,5 @@
+# module Scruffy::Helpers::MetaAttributes
+#     def singleton_class
+#       (class << self; self; end)
+#     end
+# end

data/lib/scruffy/helpers/point_container.rb

@@ -0,0 +1,99 @@
+module Scruffy::Helpers
+  
+  # ==Scruffy::Helpers::PointContainer
+  #
+  # Author:: Mat Schaffer
+  # Date:: March 22nd, 2007
+  #
+  # Allows all standard point operations to be called on both Array and Hash
+  module PointContainer
+    def self.extended point_set
+      point_set.extend(const_get("#{point_set.class.to_s}_ext"))
+    end
+
+    def sortable(values)
+      values.find_all { |v| v.respond_to? :<=> }
+    end
+    
+    def summable(values)
+      values.find_all { |v| v.respond_to? :+ }
+    end
+    
+    def maximum_value
+      sortable(values).sort.last
+    end
+    
+    def minimum_value
+      sortable(values).sort.first
+    end
+    
+    def sum
+      summable(values).inject(0) { |sum, i| sum += i }
+    end
+    
+    def inject_with_index memo
+      index = 0
+      inject(memo) do |memo, item|
+        ret = yield memo, item, index
+        index = index.succ
+        ret
+      end
+    end
+    
+    def minimum_key
+      sortable(keys).sort.first
+    end
+      
+    def maximum_key
+      sortable(keys).sort.last
+    end
+    
+    module Array_ext
+      def values
+        return self unless is_coordinate_list?
+        collect { |x,y| y}
+      end
+      
+      def keys
+        return [0,size-1] unless is_coordinate_list?
+        collect { |x,y| x}
+      end
+      
+      def is_coordinate_list?
+        if any? && first.is_a?(Array) && first.size == 2
+          return true
+        end
+        return false
+      end
+      
+      def each_point(&block)
+        if is_coordinate_list?
+          each{|x,y|block.call(x,y)}
+        else
+          size.times{|k|block.call(k,self[k])}
+        end
+      end
+    end
+    
+    module Hash_ext
+      def is_coordinate_list?
+        true
+      end
+      
+      def each_point(&block)
+        keys.sort.each{|k|block.call(k,self[k])}
+      end
+      
+      def inject memo
+        keys.sort.each do |k|
+          memo = yield memo, self[k]
+        end
+        memo
+      end
+      
+      def size
+        maximum_key - minimum_key + 1
+      end
+    end
+  end
+end