scruffy 0.2.0 → 0.2.1

data/CHANGES

@@ -1,5 +1,13 @@
 = Scruffy Changelog
 
+== Version 0.2.1
+(August 18th, 2006)
+
+* Mostly documentation.
+* Added Builder 2.0 dependency to gem spec.
+* Removed minimum size hack in RMagickRasterizer, for now.
+
+
 == Version 0.2.0
 (August 14th, 2006)
 

data/Rakefile

@@ -39,11 +39,14 @@ Rake::RDocTask.new { |rdoc|
   rdoc.title    = "Scruffy - Graphing Library for Ruby"
 #  rdoc.options << '--line-numbers --inline-source --main README --accessor adv_attr_accessor=M'
 #  rdoc.template = "#{ENV['template']}.rb" if ENV['template']
-  rdoc.rdoc_files.include('README', 'CHANGES')
+  rdoc.rdoc_files.include('README', 'CHANGES', 'MIT-LICENSE')
   rdoc.rdoc_files.include('lib/scruffy.rb')
   rdoc.rdoc_files.include('lib/scruffy/*.rb')
   rdoc.rdoc_files.include('lib/scruffy/layers/*.rb')
   rdoc.rdoc_files.include('lib/scruffy/renderers/*.rb')
+  rdoc.rdoc_files.include('lib/scruffy/components/*.rb')
+  rdoc.rdoc_files.include('lib/scruffy/helpers/*.rb')
+  rdoc.rdoc_files.include('lib/scruffy/rasterizers/*.rb')
 }
 
 spec = Gem::Specification.new do |s|
@@ -53,6 +56,7 @@ spec = Gem::Specification.new do |s|
   s.email = "brasten@nagilum.com"
   s.homepage = "http://scruffy.rubyforge.org"
   s.summary = "A powerful, clean graphing library for Ruby."
+  s.add_dependency('builder', '>= 2.0')  
   s.description = <<-EOF
     Scruffy is a Ruby library for generating powerful graphs.  It is based on
     SVG, allowing for powerful, clean code, as well as a good foundation for
@@ -84,7 +88,10 @@ task :publish_packages => [:verify_user, :verify_password, :package] do
   release_files = FileList[
     "pkg/#{PKG_FILE_NAME}.gem",
     "pkg/#{PKG_FILE_NAME}.tgz",
-    "pkg/#{PKG_FILE_NAME}.zip"
+    "pkg/#{PKG_FILE_NAME}.zip",
+    "pkg/#{PKG_FILE_NAME}.gem.md5",
+    "pkg/#{PKG_FILE_NAME}.tgz.md5",
+    "pkg/#{PKG_FILE_NAME}.zip.md5"
   ]
 
   Rake::XForge::Release.new(MetaProject::Project::XForge::RubyForge.new(PKG_NAME)) do |xf|

data/lib/scruffy.rb

@@ -1,3 +1,16 @@
+# ===Scruffy Graphing Library for Ruby
+#
+# Author:: Brasten Sager
+# Date:: August 5th, 2006
+#
+# For information on generating graphs using Scruffy, see the
+# documentation in Scruffy::Graph.
+#
+# For information on creating your own graph types, see the
+# documentation in Scruffy::Layers::Base.
+module Scruffy; end
+
+
 $:.unshift(File.dirname(__FILE__)) unless
   $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
   

data/lib/scruffy/components.rb

@@ -1,3 +1,13 @@
+# ===Scruffy Components
+#
+# Author:: Brasten Sager
+# Date:: August 16th, 2006
+#
+# Components make up the visual elements of a Scruffy graph.
+#
+# For examples, see Scruffy::Components::Base.
+module Scruffy::Components; end
+
 require 'scruffy/components/base'
 require 'scruffy/components/title'
 require 'scruffy/components/background'

data/lib/scruffy/components/viewport.rb

@@ -1,21 +1,21 @@
-module Scruffy
-  module Components
-    # Component used to limit other visual components to a certain area on the graph.
-    class Viewport < Base
-      include Scruffy::Helpers::Canvas
+module Scruffy::Components
+  # Component used to limit other visual components to a certain area on the graph.
+  class Viewport < Base
+    include Scruffy::Helpers::Canvas
+    
+    attr_accessor :components
+    
+    def initialize(*args, &block)
+      super(*args)
       
-      attr_accessor :components
-      
-      def initialize(*args, &block)
-        super(*args)
-        
-        self.components = []
-        if block
-          block.call(self.components)
-        end
+      self.components = []
+      if block
+        block.call(self.components)
       end
+    end
 
-      def draw(svg, bounds, options={})
+    def draw(svg, bounds, options={})
+      svg.g(options_for) {
         self.components.each do |component|
             component.render(svg, 
                              bounds_for( [bounds[:width], bounds[:height]], 
@@ -23,8 +23,20 @@ module Scruffy
                                          component.size ), 
                              options)
         end
-
-      end
+      }
     end
+    
+    private
+      def options_for
+        options = {}
+        %w(skewX skewY).each do |option|
+          if @options[option.to_sym]
+            options[:transform] ||= ''
+            options[:transform] = options[:transform] + "#{option.to_s}(#{@options[option.to_sym]})"
+          end
+        end
+        
+        options
+      end
   end
 end

data/lib/scruffy/formatters.rb

@@ -1,111 +1,176 @@
-module Scruffy
-  module Formatters
-    class Base
-      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
+# ===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)
-          sprintf("%01.#{precision}f", number)
-        end
+    protected
+      def number_with_precision(number, precision=3)  #:nodoc:
+        sprintf("%01.#{precision}f", number)
+      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.
+    def initialize(options = {})
+      @precision        = options[:precision] || :none
+      @separator        = options[:separator] || '.'
+      @delimiter        = options[:delimiter] || ','
+      @precision_limit  = options[:precision_limit] || 4
     end
     
-    # Default number formatter.  Limits precision, beautifies numbers.
-    class Number < Base
-      attr_accessor :precision, :separator, :delimiter, :precision_limit
+    # Formats the value.
+    def format(target, idx, options)
+      my_precision = @precision
       
-      def initialize(options = {})
-        @precision        = options[:precision] || :none
-        @separator        = options[:separator] || '.'
-        @delimiter        = options[:delimiter] || ','
-        @precision_limit  = options[:precision_limit] || 4
+      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
       
-      def format(target, idx, options)
-        my_precision = @precision
+      my_separator = @separator
+      my_separator = "" unless my_precision > 0
+      begin
+        parts = number_with_precision(target, my_precision).split('.')
         
-        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
-          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
-          number
-        rescue StandardError => e
-          target
-        end
+        number = parts[0].to_s.gsub(/(\d)(?=(\d\d\d)+(?!\d))/, "\\1#{@delimiter}") + my_separator + parts[1].to_s
+        number
+      rescue StandardError => e
+        target
       end
     end
+  end
+  
+  # Currency formatter.
+  #
+  # Provides formatting for currencies.
+  class Currency < Base
     
-    class Currency < Base
-      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
-      
-      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
+    # 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
     
-    class Percentage < Base
-      def initialize(options = {})
-        @precision    = options[:precision] || 3
-        @separator    = options[:separator] || '.'
-      end
-      
-      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
+    # 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

@@ -1,13 +1,3 @@
-# ===Scruffy Graphing Library for Ruby
-#
-# Author:: Brasten Sager
-# Date:: August 5th, 2006
-#
-# For information on generating graphs using Scruffy, see the
-# documentation in Scruffy::Graph.
-#
-# For information on creating your own graph types, see the
-# documentation in Scruffy::Layers::Base.
 module Scruffy
   
   # ==Scruffy Graphs
@@ -21,7 +11,7 @@ module Scruffy
   # 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::GraphLayers as
+  # Despite the technical distinction, we will refer to Scruffy::Graph objects as 'graphs' and Scruffy::Layers as
   # 'layers' or 'graph types.'
   #
   #
@@ -34,7 +24,7 @@ module Scruffy
   #
   #   OR
   #
-  #   graph = Scruffy::Graph.new(:title => "Monthly Profits", :theme => Scruffy::Themes::RUBY_BLOG)
+  #   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
@@ -49,13 +39,21 @@ module Scruffy
   #   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 with the Graph#render method:
+  # 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(:size => [1500, 1000])
+  #   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.
@@ -93,7 +91,7 @@ module Scruffy
     # Options:
     #
     # title::  Graph's title
-    # theme::  A theme hash to use when rendering graph
+    # 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
@@ -128,7 +126,7 @@ module Scruffy
     #
     # 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.
+    # 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
@@ -140,16 +138,16 @@ module Scruffy
       options[:max_value]           ||= top_value
       options[:graph]               ||= self
       
-      
-      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))]
-        puts options[:size].inspect
-      end
+
+      # 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 ) )
-
-      options[:size] = options[:actual_size] if options[:actual_size]
       
       # SVG to file.
       if options[:to] && options[:as].nil?