prawn-graph 1.0.0.pre1 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 84da9cfac88ce76e053409afd8ea057d8fb165b6
-  data.tar.gz: 0dc84a38ede9e63fae98301613f57c89c9d4970b
+  metadata.gz: 6390e1f2b56cd0e602ed9bad9f9e79d8bf8d24fd
+  data.tar.gz: 5a17ad2247533d9a61a26043521e26c7dd21f1f8
 SHA512:
-  metadata.gz: 2d7a8b4568f6cd91c062d2811cca83d077b086ea76d71e38ac0c5f2cb660636fd1043f2f3c68b3fb1bedd204629fb746a368daa3074afee9088b1c964d361a1c
-  data.tar.gz: 98609b55fe0f6cca079bf8b3421ee6fbd9315f1737c2278c0ec4c6e099ecdae658a9f8c37b8e9411c3198830695311eea9b682fca7bd6c44fcb17742549f6b8e
+  metadata.gz: 18a28570e31af7e7d7dce328cfd1277d50e13c255d47afa015ef3a8fc0e06d76f64e43c726b0c5a67afb885ed2ede934d5f73e7f16d52d18ae8136fabcfbdf5e
+  data.tar.gz: 8dd7705229fa6450dd46f8a679560299a9feba69a7356f9c7f60e4326e9ba65eade94c5f77cb1d94679477de849cc48da21dbd2ff4355848ad9cb324c14dc8e9

data/.travis.yml

@@ -1,7 +1,17 @@
 language: ruby
 rvm:
   - 2.0.0
+  - 2.1.0-p0
   - 2.1.8
+  - 2.2.0-p0
   - 2.2.4
   - 2.3.0
+  - jruby-9.0.5.0
+  - rbx-3.19
+matrix:
+  allow_failures:
+    - rvm: rbx-3.19
 before_install: gem install bundler -v 1.11.2
+addons:
+    code_climate:
+        repo_token: 9646aae52d1d1670d545c46bd94f5d86b92d516c5e3cb9890fcef62acc3a34b6

data/README.md

@@ -2,6 +2,16 @@
 
 [![Gem Version](https://badge.fury.io/rb/prawn-graph.svg)](https://badge.fury.io/rb/prawn-graph)
 [![License](http://img.shields.io/:license-mit-blue.svg)](http://sujrd.mit-license.org)
+[![Code Climate](https://codeclimate.com/github/HHRy/prawn-graph/badges/gpa.svg)](https://codeclimate.com/github/HHRy/prawn-graph)
+[![Test Coverage](https://codeclimate.com/github/HHRy/prawn-graph/badges/coverage.svg)](https://codeclimate.com/github/HHRy/prawn-graph/coverage)
+[![Build Status](https://travis-ci.org/HHRy/prawn-graph.svg?branch=master)](https://travis-ci.org/HHRy/prawn-graph)
+[![security](https://hakiri.io/github/HHRy/prawn-graph/master.svg)](https://hakiri.io/github/HHRy/prawn-graph/master)
+![Maintained: yes](https://img.shields.io/badge/maintained-yes-brightgreen.png)
+
+**This readme reflects the state of _master_ which is not the released version of prawn-graph.**
+
+**The code being used to cut gems for release is the `stable` Branch, please make pull requests for**
+**bug fixes from that branch.**
 
 An extension for the [prawn pdf library][5] which adds the ability to draw graphs (or charts if
 you perfer) in PDF documents.
@@ -13,42 +23,43 @@ are dramatic.
 
 By default, graphs are drawn in monochrome, as that's likely how they will be printed. 
 
+This is free and open source software released under ther terms of the [MIT Licence](http://opensource.org/licenses/MIT).
+
+Its copyright is held by Ryan Stenhouse and the [other contributors][8] and it was first released in 
+2010.
+
 ## Compatibility
 
-The gem is  only tested against Ruby version 2.0 and greater. Older Ruby versions may work but are not 
+This gem is built assuming a Ruby version of 2.0 or higher. Older Ruby versions may work but are not 
 officially supported. We aim for compatibilty with 1.x and 2.x series of prawn. Any incomaptibilities
-should be treated as bugs and added to the [issue tracker][2]. 
-
-Unlike previous version of prawn-graph, this version does not at this time include a theme api or the 
-ability to change the colors used to render the graph. 
+with prawn versions should be treated as bugs and added to the [issue tracker][2]. 
 
+We build automatically using Travis CI. Our [.travis.yml][9] file targets the same Ruby versions as
+[prawn itself][5] does.
 
-## IMPORTANT - READ THIS BEFORE USING
 
-prawn-graph is currently being rewritten to have its internal components replaced with new, properly
-test-driven bits of code to draw the various cool graphs and charts that people would like to use in
-their PDFs.
+### Removed features:
 
-Right now, the "legacy" drawing code is what is ultimately being used to render any graphs being 
-generated. The newness instead is that project is compatible with all modern versions of prawn and
-therefore are useful again.
+Unlike previous versions of `prawn-graph`, this version does not at this time include a theme api or the 
+ability to change the colors used to render the graph. 
 
-This means that for now any existing rendering bugs still remain. If you find any, please be
-[a good citizen][2] and [report them][2].
+## Installation
 
-To use prawn-graph with these caveats, you can add the following to your `Gemfile`:
+To use prawn-graph, you can add the following to your `Gemfile`:
 
 ```Gemfile
- gem 'prawn-graph', '1.0.0.pre1'
+ gem 'prawn-graph', ' ~> 1.0'
 ```
 
-Alternatively, you can use Rubygems directly: `gem install prawn-graph --pre`.
+Alternatively, you can use Rubygems directly: `gem install prawn-graph`.
  
 ## Acknowledgements
 
 With thanks to [株式会社アルム][3] ([Allm Inc][4]) for allowing Ryan Stenhouse the time to rebuild this version of
 prawn-graph. This updated version of prawn-graph was inspired and guided by [prawn-svg][1] by [Roger Nesbitt][6]. 
-It also uses some of [prawn-svg][1]'s document size calculation code.
+
+Prawn Graph was originally sponsored by and built for use at [Purchasing Card Consultancy Ltd][7] while
+Ryan Stenhouse was employed there.
 
 ## Supported graph / chart types
 
@@ -62,39 +73,64 @@ adventurous - please add it!
 
 ## Using prawn-graph
 
-```ruby
-  require 'prawn-graph'
-
-  data = [ ['A', 10], ['B', 11], ['C', 12] ]
+Graphs can be created by calling the `graph` or its alias, `chart` method with an array of
+`Prawn::Graph::Series` objects representing the data you would like to plot and how it should
+be displayed. It will also take a hash of options, and block which will have the graph yeilded
+to it.
 
-  Prawn::Document.generate('test.pdf') do
-    text 'Graph Example'
-    bar_graph data
-  end
+```ruby
+  graph data, options = {}, &block.
 ```
 
 When called with just a set of data, prawn-graph will do its best to make the graph fit in the 
 available space. For a little more control over how the graphs are rendered in the document
-you can pass the following options:
+you can pass the following options to `graph` or `chart`:
 
 Option      | Data type | Description
 ----------- | --------- | -----------
 :at         | [integer, integer] | Specify the location on the page you want the graph to appear.
 :width      | integer   | Desired width of the graph.  Defaults to horizontal space available.
 :height     | integer   | Desired height of the graph.  Defaults to vertical space available.
+:title      | string    | The overall title for your chart
+:series_key | boolean   | Should we render the series key for multi series graphs? Defaults to true.
+
+The `data` passed to `graph` or `chart` should be an `Array` of `Prawn::Graph::Series` objects, which
+themselves are made up of an array of data points to plot, and a series of options.
+
+```ruby
+  Prawn::Graph::Series.new [1,2,3,4], options = {}
+```
 
-### Example
+Valid `options` are:
+
+Option        | Data type | Description
+------------- | --------- | -----------
+:mark_average | boolean   | Should we mark a line showing the average value of the series? Defaults to false.
+:mark_minimum | boolean   | Should we mark the minimum value of the series? Defaults to false.
+:mark_maximum | boolean   | Should we mark the maximum value of the series? Defaults to false.
+:title        | string    | The title of this series, which will be shown in the series key.
+:type         | symbol    | How this series should be rendered. Defaults to `:bar`, valid options are `:bar`, `:line`.
+
+### Show me some code!
 
 ```ruby
   require 'prawn-graph'
 
-  data = [ ['A', 10], ['B', 11], ['C', 12] ]
+  series = []
+  series << Prawn::Graph::Series.new([4,9,3,2,1,6,2,8,2,3,4,9,2],  title: "A label for a series", type: :bar)
+  series << Prawn::Graph::Series.new([5,4,3,2,7,9,2,8,7,5,4,9,2],  title: "Another label", type: :line, mark_average: true, mark_minimum: true)
+  series << Prawn::Graph::Series.new([1,2,3,4,5,9,6,4,5,6,3,2,11], title: "Yet another label", type: :bar)
+  series << Prawn::Graph::Series.new([1,2,3,4,5,12,6,4,5,6,3,2,9].shuffle, title: "One final label", type: :line, mark_average: true, mark_maximum: true)
+
+  xaxis_labels = ['0900', '1000', '1100', '1200', '1300', '1400', '1500', '1600', '1700', '1800', '1900', '2000', '2100']
 
   Prawn::Document.generate('test.pdf') do
-    text 'Graph Example'
-    bar_graph data, at: [10,20], width: 200
+    graph series, width: 500, height: 200, title: "A Title for the chart", at: [10,700], xaxis_labels: xaxis_labels
   end
-```
+``` 
+
+### Output
+<img src="http://prawn-graph.ryanstenhouse.jp/img/prawn-graph-output.png" alt="Prawn Graph Example Output" width="933" height="420">
 
 ## Development
 
@@ -111,9 +147,6 @@ Bug reports and pull requests are welcome [on GitHub][2]. This project is intend
 safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) 
 code of conduct.
 
-## License
-
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
 
 [1]: https://github.com/mogest/prawn-svg/
@@ -121,4 +154,7 @@ The gem is available as open source under the terms of the [MIT License](http://
 [3]: http://www.allm.net/
 [4]: http://www.allm.net/en/
 [5]: http://github.com/prawnpdf/prawn/
-[6]: https://github.com/mogest/
+[6]: https://github.com/mogest/
+[7]: http://www.pccl.co.uk/
+[8]: https://github.com/HHRy/prawn-graph/blob/master/CONTRIBUTORS.md
+[9]: https://github.com/HHRy/prawn-graph/blob/master/.travis.yml

data/Rakefile

@@ -1,5 +1,11 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require 'yard'
+
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb', '-', '*.md']
+end
 
 RSpec::Core::RakeTask.new(:spec)
 

data/lib/prawn-graph.rb

@@ -1,8 +1,13 @@
+require "ostruct"
+require "bigdecimal"
 require "prawn"
 require "prawn/graph/version"
+require "prawn/graph/calculations"
+
+require "prawn/graph/chart_components"
+
 require "prawn/graph/theme"
 require "prawn/graph/series"
-require "prawn/graph/charts"
 
 require "prawn/graph/extension"
 

data/lib/prawn/graph/calculations.rb

@@ -0,0 +1 @@
+require_relative "calculations/layout_calculator"

data/lib/prawn/graph/calculations/layout_calculator.rb

@@ -0,0 +1,109 @@
+module Prawn
+  module Graph
+    module Calculations
+
+      class LayoutCalculator
+        attr_reader :bounds
+        attr_reader :series_key_area, :title_area, :graph_area, :canvas_width, :canvas_height
+
+        class Dimensions < OpenStruct
+          def renderable?
+            width > 0 && height > 0
+          end
+
+          def point
+            [x, y]
+          end
+        end
+
+        def initialize(bounds, attributes = nil, theme = Prawn::Graph::Theme::Default)
+          @bounds = bounds
+          @graph_area       = Dimensions.new({ width: 0, height: 0, x: 0, y: 0 })
+          @title_area       = Dimensions.new({ width: 0, height: 0, x: 0, y: 0 })
+          @series_key_area  = Dimensions.new({ width: 0, height: 0, x: 0, y: 0 })
+          @theme            = theme
+          set_from_attributes(attributes) if attributes
+        end
+
+        def calculate
+          calculate_width_and_height_of_canvas
+          calculate_key_area
+          calculate_title_area
+          calculate_graph_area
+          
+          self
+        end
+
+        def hpadding
+          ((BigDecimal(canvas_width) / 100) * 2).round
+        end
+
+        def vpadding
+          ((BigDecimal(canvas_height) / 100) * 2).round
+        end
+
+        def invalid?
+          canvas_width > bounds[0] || canvas_height > bounds[1]
+        end
+
+        private
+
+        def set_from_attributes(attributes)
+          @canvas_width = BigDecimal(attributes[:width], 10) rescue 0
+          @canvas_height = BigDecimal(attributes[:height], 10) rescue 0
+          @num_series = attributes[:series_count] || 1
+          @title = attributes[:title]
+          @show_series_key = !attributes[:show_series_key].nil? ? attributes[:show_series_key]  : true
+        end
+
+        def calculate_width_and_height_of_canvas
+          if @canvas_width.zero? && @canvas_height.zero?
+            @canvas_width   = BigDecimal(bounds[0], 10) 
+            @canvas_height  = BigDecimal(bounds[1], 10) 
+          elsif !@canvas_width.zero? && @canvas_height.zero?
+            @canvas_height  = (@canvas_width / bounds_aspect_ratio).round
+          elsif !@canvas_height.zero? && @canvas_width.zero?
+            @canvas_width  = (@canvas_height * bounds_aspect_ratio).round
+          end
+        end
+
+        def bounds_aspect_ratio
+          BigDecimal(bounds[0], 10) / BigDecimal(bounds[1], 10)
+        end
+
+        def calculate_title_area
+          unless @title.nil?
+            @title_area[:width] = (canvas_width - @series_key_area[:width] - (2*hpadding))
+            @title_area[:x] = hpadding
+            @title_area[:height] = @theme.font_sizes.main_title + vpadding
+            @title_area[:y] = canvas_height + vpadding 
+          end
+        end
+
+        def calculate_key_area
+          if @num_series > 1 && @show_series_key
+            @series_key_area[:width] = ( (canvas_width / 100) * 25 ).round
+            @series_key_area[:x] = (canvas_width - @series_key_area[:width] - hpadding)
+            @series_key_area[:y] = canvas_height + vpadding
+            @series_key_area[:height] = (canvas_height - vpadding)
+          end 
+        end
+
+        def calculate_graph_area
+          @graph_area[:width] = (canvas_width - @series_key_area[:width] - (2*hpadding))
+          @graph_area[:x] = hpadding
+
+          if !@title_area.renderable?
+            @graph_area[:y] = canvas_height + vpadding
+            @graph_area[:height] = (canvas_height - vpadding)
+          else
+            @graph_area[:y] =  (@title_area[:y] - @title_area[:height])
+            @graph_area[:height] = (canvas_height - vpadding - @title_area[:height])
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/prawn/graph/chart_components.rb

@@ -0,0 +1,4 @@
+require_relative "chart_components/series_renderer"
+require_relative "chart_components/bar_chart_renderer"
+require_relative "chart_components/line_chart_renderer"
+require_relative "chart_components/canvas"

data/lib/prawn/graph/chart_components/bar_chart_renderer.rb

@@ -0,0 +1,94 @@
+module Prawn
+  module Graph
+    module ChartComponents
+      # The Prawn::Graph::ChartComponents::BarChartRenderer is used to plot one or more bar charts 
+      # in a sensible way on a a Prawn::Graph::ChartComponents::Canvas and its associated 
+      # Prawn::Document.
+      #
+      class BarChartRenderer < SeriesRenderer
+        def render
+          render_the_chart
+        end
+
+        private
+
+        def mark_average_line(series_index)
+          if @series[series_index].mark_average?
+            average_y_coordinate = (point_height_percentage(@series[series_index].avg) * @plot_area_height) - 5
+            prawn.line_width = 1
+            prawn.stroke_color = @color[series_index]
+            prawn.dash(2)
+            prawn.stroke_line([0, average_y_coordinate], [ @plot_area_width, average_y_coordinate ])
+            prawn.undash
+          end
+        end
+
+        def mark_maximum_point(series_index, point, max_marked, x_position, y_position)
+          if @series[series_index].mark_maximum? && max_marked == false && @series[series_index].values[point] == @series[series_index].max
+            max_marked = draw_marker_point(@canvas.theme.max, x_position, y_position)
+          end
+
+          max_marked
+        end
+
+        def mark_minimum_point(series_index, point, min_marked, x_position, y_position)
+          if @series[series_index].mark_minimum? && min_marked == false && !@series[series_index].values[point].zero? && @series[series_index].values[point] == @series[series_index].min
+            min_marked = draw_marker_point(@canvas.theme.min, x_position, y_position)
+          end
+
+          min_marked
+        end
+
+        def render_the_chart
+          prawn.bounding_box [@graph_area.point[0] + 5, @graph_area.point[1] - 20], width: @plot_area_width, height: @plot_area_height do
+         
+            prawn.save_graphics_state do  
+              num_points        = @series[0].size
+              width_per_point   = (@plot_area_width / num_points)
+              width             = (((width_per_point * 0.9) / @series.size).round(2)).to_f
+              min_marked        = false
+              max_marked        = false
+
+              num_points.times do |point|
+
+                @series.size.times do |series_index|
+                  series_offset = series_index + 1
+                  prawn.fill_color    = @color[series_index]
+                  prawn.stroke_color  = @color[series_index]
+                  prawn.line_width  = width
+
+                  starting = (prawn.bounds.left + (point * width_per_point))
+
+                  x_position = ( (starting + (series_offset * width) ).to_f - (width / 2.0))
+                  y_position = ((point_height_percentage(@series[series_index].values[point]) * @plot_area_height) - 5).to_f
+
+                  prawn.fill_and_stroke_line([ x_position ,0], [x_position ,y_position]) unless @series[series_index].values[point].zero?
+
+                  mark_average_line(series_index)
+                  max_marked = mark_maximum_point(series_index, point, max_marked, x_position, y_position)
+                  min_marked = mark_minimum_point(series_index, point, min_marked, x_position, y_position)
+                end
+
+              end
+
+            end
+            render_axes
+          end
+        end
+
+        def max 
+          @series.collect(&:max).max || 0
+        end
+
+        def min
+          @series.collect(&:min).min || 0
+        end
+
+        def avg
+          @series.collect(&:avg).inject(:+) / @series.size rescue 0
+        end
+
+      end
+    end
+  end
+end