prawn-graph 0.0.2 → 0.0.3

data/README.markdown

@@ -1,3 +1,52 @@
-# prawn-graph - Easy Graphing for Prawn
+# Prawn::Graph - Easy Graphing for Prawn
 
-More content to come soon, I promise!
+Prawn::Graph copyrighted free software by Ryan Stenhouse
+<ryan@ryanstenhouse.eu> with contributions form the community.
+
+It extends Prawn::Core to add the ability for people to natively
+draw graphs and charts in their PDFs.
+
+Because Prawn::Graph only uses the native PDF drawing functions
+exposed by Prawn, it removes the need to depend on projects like
+Gruff to insert graphs in your documents. The results may not be
+as pretty (yet), but the file-size differences are dramatic.
+
+By default, graphs are drawn in monochrome, as that's likely how
+they will be printed. You can pass an option to each of the graph
+methods which will draw them in colour.
+
+**Notice!** Much like Prawn, this software should be considered to
+be in early alpha state at best. It's not recommended for use in 
+a production environment unless you're happy to put up with bugs and
+are willing to help fix them!
+
+## Branches
+
+The master branch of this repository tracks edge Prawn and will
+be updated to reflect any changes there. If you need to work on
+a version which is compatible with the current stable release,
+0.7.*, then please use the <tt>stable-compat</tt> branch instead.
+
+## Installing & Using through RubyGems
+
+Installing and running prawn-graph is very easy:
+
+  * <tt>gem install prawn prawn-graph</tt>
+
+Will give you the latest 'stable' version of Prawn and the latest
+compatible version of prawn-graph. 
+
+Using graphs in your PDF is as straightforward as:
+
+<pre>
+  require 'rubygems'
+  require 'prawn/core'
+  require 'prawn/graph'
+
+  data = [ ['A', 10], ['B', 11], ['C' 12] ]
+
+  Prawn::Document.generate('test.pdf') do
+    test 'Graph Example'
+    bar_graph data at => [10,10]
+  end
+</pre>

data/Rakefile

@@ -1,8 +1,9 @@
 require 'rubygems'
 require 'rake'
 require "rake/gempackagetask" 
+require "rake/rdoctask"
 
-PRAWN_GRAPH_VERSION = '0.0.2'
+PRAWN_GRAPH_VERSION = '0.0.3'
 
 spec = Gem::Specification.new do |spec|
   spec.name = "prawn-graph"
@@ -17,15 +18,28 @@ spec = Gem::Specification.new do |spec|
   spec.has_rdoc = true
   spec.extra_rdoc_files = %w{README.markdown}
   spec.rdoc_options << '--title' << 'Prawn Documentation' <<
-                       '--main' << 'README.markdown' << '-q'
+                       '--main' << 'README' << '-q'
   spec.author = "Ryan Stenhouse"
   spec.email = " ryan@ryanstenhouse.eu"
   spec.rubyforge_project = "prawn"
+  spec.add_dependency 'prawn'
   spec.homepage = "http://ryanstenhouse.eu"
   spec.description = <<END_DESC
   An extension to Prawn that provides the ability to draw basic graphs and charts natively in your PDFs.
 END_DESC
 end
+
+desc "genrates documentation"
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_files.include( "README.markdown",
+                           "COPYING",
+                           "LICENSE", 
+                           "HACKING", "lib/" )
+  rdoc.main     = "README.markdown"
+  rdoc.rdoc_dir = "doc/html"
+  rdoc.title    = "Prawn Documentation"
+end     
+
  
 Rake::GemPackageTask.new(spec) do |pkg|
   pkg.need_zip = true

data/lib/prawn/graph.rb

@@ -2,6 +2,7 @@ require 'bigdecimal'
 
 require File.dirname(__FILE__) + '/graph/errors'
 require File.dirname(__FILE__) + '/graph/chart'
+require File.dirname(__FILE__) + '/graph/base'
 require File.dirname(__FILE__) + '/graph/grid'
 require File.dirname(__FILE__) + '/graph/bar'
 require File.dirname(__FILE__) + '/graph/line'
@@ -10,10 +11,6 @@ module Prawn
 
   class Document
 
-    # Adds compatibility with the current stable version of prawn 
-    #
-    alias draw_text text
-
     # Draws a fairly simple bar chart. Data should be passed in as an array of
     # arrays, much like how Tables are dealt with:
     #

data/lib/prawn/graph/bar.rb

@@ -1,48 +1,48 @@
 module Prawn
   module Chart
-    class Bar
-      
-      attr_accessor :grid, :headings, :values, :highest_value, :document, :colour
+    
+    # Prawn::Chart::Bar plots its values as a Bar graph, relatively
+    # sized to fit within the space defined by the Prawn::Chart::Grid
+    # associated with it.
+    #
+    # Call to new will return a new instance of Prawn::Chart::Bar ready to
+    # be rendered.
+    #
+    # Takes an Array of +data+, which should contain complete rows of data for
+    # values to be plotted; a reference to a +document+ which should be an 
+    # instance of Prawn::Document and an +options+ with at least a value for :at
+    # specified.
+    #
+    # Options are:
+    #
+    #  :at , which should be an Array representing the point at which the graph
+    #  should be drawn.
+    #
+    #  :title, the title for this graph, wil be rendered centered to the top of 
+    #  the Grid.
+    #
+    #  :label_x, a label to be shown along the X axis of he graph, rendered centered
+    #  on the grid.
+    #
+    #  :label_y, a label to be shown along the Y axis of he graph, rendered centered
+    #  on the grid and rotated to be perpendicular to the axis.
+    #
+    # Data should be formatted like:
+    #
+    #    [
+    #      [ 'Column Heading', SomeValue ],
+    #      [ 'Column Heading', SomeValue ],
+    #      [ 'Column Heading', SomeValue ],
+    #      [ 'Column Heading', SomeValue ],
+    #      [ 'Column Heading', SomeValue ],
+    #      [ 'Column Heading', SomeValue ]
+    #    ]
+    #
+    class Bar < Base
 
-      def initialize(data, document, options = {})
-        if options[:at].nil? || options[:at].empty?
-          raise Prawn::Errors::NoGraphStartSet,
-            "you must specify options[:at] as the coordinates wher you" +
-            " wish this graph to be drawn from."
-        end
-        opts = { :width => 500, :height => 200, :spacing => 20 }.merge(options)
-        (@headings, @values, @highest_value) = process_the data
-        (grid_x_start, grid_y_start, grid_width, grid_height) = parse_sizing_from opts 
-        @colour = (!opts[:use_color].nil? || !opts[:use_colour].nil?)
-        @document = document
-        @grid = Prawn::Chart::Grid.new(grid_x_start, grid_y_start, grid_width, grid_height, opts[:spacing], document)
-      end
   
-      def draw
-        @grid.draw
-        label_axes
-        if @title
-          draw_title
-        end
-        plot_values
-        if @x_label
-          draw_x_axis_label
-        end 
-        if @y_label
-          draw_y_axis_label
-        end 
-       reset
-      end
-    
       private
 
-      def reset
-        @document.line_width 1
-        @document.stroke_color '000000'
-        @document.fill_color '000000'
-        @document.move_to @grid.point
-      end
-
       def plot_values
         base_x = @grid.start_x + 1
         base_y = @grid.start_y + 1
@@ -63,110 +63,6 @@ module Prawn
         end
       end
 
-      def label_axes
-        base_x = @grid.start_x + 1
-        base_y = @grid.start_y + 1
-
-        # Put the values up the Y Axis
-        #
-        @document.draw_text @highest_value, :at => [base_x - 15, base_y + @grid.height], :size => 5
-        @document.draw_text '0', :at => [base_x - 15, base_y ], :size => 5
-    
-        # Put the column headings along the X Axis
-        #
-        point_spacing = calculate_plot_spacing 
-        last_position = base_x + (point_spacing / 2)
-        @headings.each do |heading|
-          @document.draw_text heading, :at => [last_position, base_y - 15 ], :size => 5
-          last_position += point_spacing
-        end
-      end
-
-      def draw_x_axis_label
-        x_coord = calculate_x_axis_center_point(@x_label, 8)
-        y_coord = @grid.start_y - 30
-        @document.draw_text @x_label, :at => [x_coord, y_coord] ,:size => 8
-      end
-
-      def draw_y_axis_label
-        y_coord = calculate_y_axis_center_point(@y_label, 8)
-        x_coord = @grid.start_x - 30
-        @document.draw_text @y_label, :at => [x_coord, y_coord] ,:size => 8, :rotate => 90
-      end
-
-      def draw_title
-        x_coord = calculate_x_axis_center_point(@title, 10)
-        y_coord = @grid.start_y + @grid.height + 10
-        @document.draw_text @title, :at => [x_coord, y_coord] ,:size => 10
-      end
-
-      def parse_sizing_from(o)
-        x_offset = 15
-        y_offset = 0
-        move_y_up = 0
-        grid_width = o[:width]
-        grid_height = o[:height]
-
-        # Make room for the title if we're choosing to Render it.
-        #
-        if o[:title]
-          @title = o[:title]
-          y_offset += 10 
-        end
-
-        # Make room for X Axis labels if we're using them.
-        #
-        if o[:label_x]
-          y_offset += 30
-          move_y_up += 30
-          @x_label = o[:label_x]
-        end
-
-        # Make room for Y Axis labels if we're using them.
-        #
-        if o[:label_y]
-          @y_label = o[:label_y]
-          x_offset += 15
-        end
-    
-        # Return the values calculated here.
-        #
-        [ (o[:at][0] + x_offset), (o[:at][1] + move_y_up), (grid_width - x_offset), (grid_height - y_offset) ]
-      end
-
-      def process_the(data_array)
-        col = []
-        val = []
-        data_array.each { |i| val << i[1]; col << i[0] }
-        [ col, val ,val.sort.last ]
-      end
-
-      def calculate_x_axis_center_point(text, text_size, graph_start_x = @grid.start_x, graph_width = @grid.width)
-        ((graph_start_x + (graph_width / 2)) - ((text.length * text_size) / 4))
-      end
-      alias calculate_x_axis_centre_point calculate_x_axis_center_point
-
-      def calculate_y_axis_center_point(text, text_size, graph_start_y = @grid.start_y, graph_height = @grid.height)
-        ((graph_start_y + (graph_height / 2)) - ((text.length * text_size) / 4))
-      end
-      alias calculate_y_axis_centre_point calculate_y_axis_center_point
-
-      def calculate_plot_spacing
-        (@grid.width / @values.nitems)
-      end
-
-      def calculate_bar_width
-        calculate_plot_spacing / 2
-      end
-
-      def calculate_point_height_from(column_value)
-        cv = BigDecimal("#{column_value}")
-        hv = BigDecimal("#{@highest_value}")
-        gh = BigDecimal("#{@grid.height}")
-        percentage = (cv / (hv / 100))
-        ((gh / 100) * percentage).to_i
-      end
-
     end
   end
 end

data/lib/prawn/graph/base.rb

@@ -0,0 +1,207 @@
+module Prawn
+  module Chart
+    
+    # Prawn::Chart::Base implements the common methods shared by most of the graphs
+    # and charts whcih will need to be plotted. 
+    #
+    # All Prawn::Chart::Base instances and their children will have the following
+    # associated with them:
+    #
+    #   1. A Prawn::Chart::Grid  which is where the graph will be drawn
+    #   2. A refernce to the Prawn::Document being affected
+    #   3. A set of data to be plotted.
+    #
+    # A public draw method is available which does what it says on the tin and... 
+    # well.. draws the graph on the document it has a reference to.
+    #
+    class Base
+      
+      attr_accessor :grid, :headings, :values, :highest_value, :document, :colour
+      
+      # Returns a new instance of a graph to be drawn, really only useful for the
+      # subclasses which actually have a plot_values method declared so the data
+      # is actually rendered as a graph.
+      #
+      # Takes an Array of +data+, which should contain complete rows of data for
+      # values to be plotted; a reference to a +document+ which should be an 
+      # instance of Prawn::Document and an +options+ with at least a value for :at
+      # specified.
+      #
+      # Options are:
+      #
+      #  :at , which should be an Array representing the point at which the graph
+      #  should be drawn.
+      #
+      #  :title, the title for this graph, wil be rendered centered to the top of 
+      #  the Grid.
+      #
+      #  :label_x, a label to be shown along the X axis of he graph, rendered centered
+      #  on the grid.
+      #
+      #  :label_y, a label to be shown along the Y axis of he graph, rendered centered
+      #  on the grid and rotated to be perpendicular to the axis.
+      #
+      def initialize(data, document, options = {})
+        if options[:at].nil? || options[:at].empty?
+          raise Prawn::Errors::NoGraphStartSet,
+            "you must specify options[:at] as the coordinates wher you" +
+            " wish this graph to be drawn from."
+        end
+        opts = { :width => 500, :height => 200, :spacing => 20 }.merge(options)
+        (@headings, @values, @highest_value) = process_the data
+        (grid_x_start, grid_y_start, grid_width, grid_height) = parse_sizing_from opts 
+        @colour = (!opts[:use_color].nil? || !opts[:use_colour].nil?)
+        @document = document
+        @grid = Prawn::Chart::Grid.new(grid_x_start, grid_y_start, grid_width, grid_height, opts[:spacing], document)
+      end
+  
+      # Draws the graph on the document which we have a reference to.
+      #
+      def draw
+        @grid.draw
+        label_axes
+        if @title
+          draw_title
+        end
+        plot_values
+        if @x_label
+          draw_x_axis_label
+        end 
+        if @y_label
+          draw_y_axis_label
+        end 
+       reset
+      end
+
+      private
+    
+      def label_axes
+        base_x = @grid.start_x + 1
+        base_y = @grid.start_y + 1
+
+        # Put the values up the Y Axis
+        #
+        @document.draw_text @highest_value, :at => [base_x - 15, base_y + @grid.height], :size => 5
+        @document.draw_text '0', :at => [base_x - 15, base_y ], :size => 5
+    
+        # Put the column headings along the X Axis
+        #
+        point_spacing = calculate_plot_spacing 
+        last_position = base_x + (point_spacing / 2)
+        @headings.each do |heading|
+          @document.draw_text heading, :at => [last_position, base_y - 15 ], :size => 5
+          last_position += point_spacing
+        end
+      end
+
+      def draw_title
+        x_coord = calculate_x_axis_center_point(@title, 10)
+        y_coord = @grid.start_y + @grid.height + 10
+        @document.draw_text @title, :at => [x_coord, y_coord] ,:size => 10
+      end
+
+      def draw_x_axis_label
+        x_coord = calculate_x_axis_center_point(@x_label, 8)
+        y_coord = @grid.start_y - 30
+        @document.draw_text @x_label, :at => [x_coord, y_coord] ,:size => 8
+      end
+
+      def draw_y_axis_label
+        y_coord = calculate_y_axis_center_point(@y_label, 8)
+        x_coord = @grid.start_x - 30
+        @document.draw_text @y_label, :at => [x_coord, y_coord] ,:size => 8, :rotate => 90
+      end
+      
+      # All subclasses of Prawn::Chart::Base must implement thier own plot_values
+      # method, which does the actual real heavy lifting of drawing the graph.
+      #
+      def plot_values
+        raise Prawn::Errors::NoPlotValuesMethod, 'subclasses of Prawn::Chart::Base must implement '
+                                              +  'their own plot_values method.'
+      end
+
+      def reset
+        @document.line_width 1
+        @document.stroke_color '000000'
+        @document.fill_color '000000'
+        @document.move_to @grid.point
+      end
+
+
+      # Utility methods for dealing with working out where things should be
+      # the calculations and such done here are all very rough, but are
+      # sufficient for now to plot just what we need.
+      #
+      
+      
+      def parse_sizing_from(o)
+        x_offset = 15
+        y_offset = 0
+        move_y_up = 0
+        grid_width = o[:width]
+        grid_height = o[:height]
+
+        # Make room for the title if we're choosing to Render it.
+        #
+        if o[:title]
+          @title = o[:title]
+          y_offset += 10 
+        end
+
+        # Make room for X Axis labels if we're using them.
+        #
+        if o[:label_x]
+          y_offset += 30
+          move_y_up += 30
+          @x_label = o[:label_x]
+        end
+
+        # Make room for Y Axis labels if we're using them.
+        #
+        if o[:label_y]
+          @y_label = o[:label_y]
+          x_offset += 15
+        end
+    
+        # Return the values calculated here.
+        #
+        [ (o[:at][0] + x_offset), (o[:at][1] + move_y_up), (grid_width - x_offset), (grid_height - y_offset) ]
+      end
+
+      def process_the(data_array)
+        col = []
+        val = []
+        data_array.each { |i| val << i[1]; col << i[0] }
+        [ col, val ,val.sort.last ]
+      end
+
+      def calculate_x_axis_center_point(text, text_size, graph_start_x = @grid.start_x, graph_width = @grid.width)
+        ((graph_start_x + (graph_width / 2)) - ((text.length * text_size) / 4))
+      end
+      alias calculate_x_axis_centre_point calculate_x_axis_center_point
+
+      def calculate_y_axis_center_point(text, text_size, graph_start_y = @grid.start_y, graph_height = @grid.height)
+        ((graph_start_y + (graph_height / 2)) - ((text.length * text_size) / 4))
+      end
+      alias calculate_y_axis_centre_point calculate_y_axis_center_point
+
+      def calculate_plot_spacing
+        (@grid.width / @values.nitems)
+      end
+
+      def calculate_bar_width
+        calculate_plot_spacing / 2
+      end
+
+      def calculate_point_height_from(column_value)
+        cv = BigDecimal("#{column_value}")
+        hv = BigDecimal("#{@highest_value}")
+        gh = BigDecimal("#{@grid.height}")
+        percentage = (cv / (hv / 100))
+        ((gh / 100) * percentage).to_i
+      end
+
+
+    end
+  end
+end