samhendley-scruffy 0.2.7

data/lib/scruffy/formatters.rb

@@ -0,0 +1,213 @@
+# ===Scruffy Formatters
+#
+# Author:: Brasten Sager
+# Date:: August 16th, 2006
+#
+# Formatters are used to format the values displayed on the y-axis by
+# setting graph.value_formatter.
+#
+# Example:
+#
+#   graph.value_formatter = Scruffy::Formatters::Currency.new(:precision => 0)
+#
+module Scruffy::Formatters
+  
+  # == Scruffy::Formatters::Base
+  #
+  # Author:: Brasten Sager
+  # Date:: August 16th, 2006
+  #
+  # Formatters are used to format the values displayed on the y-axis by
+  # setting graph.value_formatter.
+  class Base
+    
+    # Called by the value marker component.  Routes the format call
+    # to one of a couple possible methods.
+    #
+    # If the formatter defines a #format method, the returned value is used
+    # as the value.  If the formatter defines a #format! method, the value passed is
+    # expected to be modified, and is used as the value.  (This may not actually work,
+    # in hindsight.)
+    def route_format(target, idx, options = {})
+      args = [target, idx, options]
+      if respond_to?(:format)
+        send :format, *args[0...self.method(:format).arity]
+      elsif respond_to?(:format!)
+        send :format!, *args[0...self.method(:format!).arity]
+        target
+      else
+        raise NameError, "Formatter subclass must container either a format() method or format!() method."
+      end
+    end
+
+    protected
+      def number_with_precision(number, precision=3)  #:nodoc:
+        sprintf("%01.#{precision}f", number)
+      end
+  end
+  
+  # Allows you to pass in a Proc for use as a formatter.
+  #
+  # Use:
+  #
+  # graph.value_formatter = Scruffy::Formatters::Custom.new { |value, idx, options| "Displays Returned Value" }
+  class Custom < Base
+    attr_reader :proc
+    
+    def initialize(&block)
+      @proc = block
+    end
+    
+    def format(target, idx, options)
+      proc.call(target, idx, options)
+    end
+  end
+  
+  
+  
+  # Default number formatter.
+  # Limits precision, beautifies numbers.
+  class Number < Base
+    attr_accessor :precision, :separator, :delimiter, :precision_limit
+    
+    # Returns a new Number formatter.
+    #
+    # Options:
+    # precision:: precision to use for value.  Can be set to an integer, :none or :auto.
+    #             :auto will use whatever precision is necessary to portray all the numerical
+    #             information, up to :precision_limit.
+    #
+    #             Example:  [100.1, 100.44, 200.323] will result in [100.100, 100.440, 200.323]
+    #
+    # separator:: decimal separator.  Defaults to '.'
+    # delimiter:: delimiter character.  Defaults to ','
+    # precision_limit:: upper limit for auto precision. (Ignored if roundup is specified)
+    # roundup:: round up the number to the given interval 
+    def initialize(options = {})
+      @precision        = options[:precision] || :none
+      @roundup          = options[:roundup] || :none
+      @separator        = options[:separator] || '.'
+      @delimiter        = options[:delimiter] || ','
+      @precision_limit  = options[:precision_limit] || 4
+    end
+    
+    # Formats the value.
+    def format(target, idx, options)
+      my_precision = @precision
+      
+      if @precision == :auto
+        my_precision = options[:all_values].inject(0) do |highest, current|
+          cur = current.to_f.to_s.split(".").last.size
+          cur > highest ? cur : highest
+        end
+      
+        my_precision = @precision_limit if my_precision > @precision_limit
+      elsif @precision == :none
+        my_precision = 0
+      end
+      
+      my_separator = @separator
+      my_separator = "" unless my_precision > 0
+      begin
+        number = ""
+        
+        if @roundup == :none 
+          parts = number_with_precision(target, my_precision).split('.')
+          number = parts[0].to_s.gsub(/(\d)(?=(\d\d\d)+(?!\d))/, "\\1#{@delimiter}") + my_separator + parts[1].to_s
+        else 
+          number = roundup(target.to_f, @roundup).to_i.to_s
+        end
+        
+        number
+      rescue StandardError => e
+        target
+      end
+    end
+    
+    
+    def roundup(target, nearest=100)
+      target % nearest == 0 ? target : target + nearest - (target % nearest)
+    end
+    def rounddown(target, nearest=100)
+      target % nearest == 0 ? target : target - (target % nearest)
+    end
+  end
+  
+
+  
+  # Currency formatter.
+  #
+  # Provides formatting for currencies.
+  class Currency < Base
+    
+    # Returns a new Currency class.
+    #
+    # Options:
+    # precision:: precision of value
+    # unit:: Defaults to '$'
+    # separator:: Defaults to '.'
+    # delimiter:: Defaults to ','
+    # negative_color:: Color of value marker for negative values.  Defaults to 'red'
+    # special_negatives:: If set to true, parenthesizes negative numbers.  ie:  -$150.50 becomes ($150.50).
+    #                     Defaults to false.
+    def initialize(options = {})
+      @precision        = options[:precision] || 2
+      @unit             = options[:unit] || '$'
+      @separator        = options[:separator] || '.'
+      @delimiter        = options[:delimiter] || ','
+      @negative_color   = options[:negative_color] || 'red'
+      @special_negatives = options[:special_negatives] || false
+    end
+    
+    # Formats value marker.
+    def format(target, idx, options)
+      @separator = "" unless @precision > 0
+      begin
+        parts = number_with_precision(target, @precision).split('.')
+        if @special_negatives && (target.to_f < 0)
+          number = "(" + @unit + parts[0].to_i.abs.to_s.gsub(/(\d)(?=(\d\d\d)+(?!\d))/, "\\1#{@delimiter}") + @separator + parts[1].to_s + ")"
+        else
+          number = @unit + parts[0].to_s.gsub(/(\d)(?=(\d\d\d)+(?!\d))/, "\\1#{@delimiter}") + @separator + parts[1].to_s
+        end
+        if (target.to_f < 0) && @negative_color
+          options[:marker_color_override] = @negative_color
+        end
+        number
+      rescue
+        target
+      end
+    end
+  end
+  
+  # Percentage formatter.
+  #
+  # Provides formatting for percentages.  
+  class Percentage < Base
+    
+    # Returns new Percentage formatter.
+    #
+    # Options:
+    # precision:: Defaults to 3.
+    # separator:: Defaults to '.'
+    def initialize(options = {})
+      @precision    = options[:precision] || 3
+      @separator    = options[:separator] || '.'
+    end
+    
+    # Formats percentages.
+    def format(target)
+      begin
+        number = number_with_precision(target, @precision)
+        parts = number.split('.')
+        if parts.at(1).nil?
+          parts[0] + "%"
+        else
+          parts[0] + @separator + parts[1].to_s + "%"
+        end
+      rescue
+        target
+      end
+    end
+  end
+
+end

data/lib/scruffy/graph.rb

@@ -0,0 +1,190 @@
+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, :theme, :default_type, 
+                    :point_markers, :value_formatter, :rasterizer
+                  
+    def_delegators  :internal_state, :title=, :theme=, :default_type=,
+                    :point_markers=, :value_formatter=, :rasterizer=
+    
+    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
+    # 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
+    # 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
+
+      %w(title theme layers default_type value_formatter point_markers rasterizer).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[:point_markers]       ||= point_markers
+      options[:size]                ||= (options[:width] ? [options[:width], (options.delete(:width) * 0.6).to_i] : [600, 360])
+      options[:title]               ||= title
+      options[:layers]              ||= layers
+      options[:min_value]           ||= bottom_value(:padded)
+      options[:max_value]           ||= top_value
+      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,24 @@
+# ===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 :theme
+    attr_accessor :default_type
+    attr_accessor :point_markers
+    attr_accessor :value_formatter
+    attr_accessor :rasterizer
+    
+    def initialize
+      
+    end
+  end
+end

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,95 @@
+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 }
+      padding == :padded ? (topval - ((topval - bottom_value) * 0.15)) : 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(top_value) { |min, layer| (min = ((min > layer.bottom_value) ? layer.bottom_value : min)) unless layer.bottom_value.nil?; min }
+      above_zero = (botval > 0)
+      botval = (botval - ((top_value - botval) * 0.15))
+    
+      # 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
+
+
+    protected
+      def to_camelcase(type)  # :nodoc:
+        type.split('_').map { |e| e.capitalize }.join('')
+      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,70 @@
+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))
+    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
+    
+    module Array
+      def values
+        self
+      end
+    end
+    
+    module Hash
+      def minimum_key
+        self.keys.sort.first
+      end
+      
+      def maximum_key
+        self.keys.sort.last
+      end
+      
+      def inject memo
+        (minimum_key..maximum_key).each do |i|
+          memo = yield memo, self[i]
+        end
+        memo
+      end
+      
+      def size
+        maximum_key - minimum_key + 1
+      end
+    end
+  end
+end

data/lib/scruffy/helpers.rb

@@ -0,0 +1,12 @@
+# ==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/meta'