prawn 2.0.2 → 2.3.0

data/manual/basic_concepts/measurement.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # The base unit in Prawn is the PDF Point. One PDF Point is equal to 1/72 of
 # an inch.
 #
@@ -10,15 +10,14 @@
 # Just <code>require "prawn/measurement_extensions"</code> and it will mix some
 # helpers onto <code>Numeric</code> for converting common measurement units to
 # PDF Points.
-#
-require File.expand_path(File.join(File.dirname(__FILE__),
-                                   %w[.. example_helper]))
+
+require_relative '../example_helper'
 
 filename = File.basename(__FILE__).gsub('.rb', '.pdf')
 Prawn::ManualBuilder::Example.generate(filename) do
-  require "prawn/measurement_extensions"
+  require 'prawn/measurement_extensions'
 
-  [:mm, :cm, :dm, :m, :in, :yd, :ft].each do |measurement|
+  %i[mm cm dm m in yd ft].each do |measurement|
     text "1 #{measurement} in PDF Points: #{1.send(measurement)} pt"
     move_down 5.mm
   end

data/manual/basic_concepts/origin.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # This is the most important concept you need to learn about Prawn:
 #
 # PDF documents have the origin <code>[0,0]</code> at the bottom-left corner of
@@ -21,9 +21,8 @@
 #
 # The following snippet strokes a circle on the margin box origin. Then strokes
 # the boundaries of a bounding box and a circle on its origin.
-#
-require File.expand_path(File.join(File.dirname(__FILE__),
-                                   %w[.. example_helper]))
+
+require_relative '../example_helper'
 
 filename = File.basename(__FILE__).gsub('.rb', '.pdf')
 Prawn::ManualBuilder::Example.generate(filename) do
@@ -31,7 +30,7 @@ Prawn::ManualBuilder::Example.generate(filename) do
 
   stroke_circle [0, 0], 10
 
-  bounding_box([100, 300], :width => 300, :height => 200) do
+  bounding_box([100, 300], width: 300, height: 200) do
     stroke_bounds
     stroke_circle [0, 0], 10
   end

data/manual/basic_concepts/other_cursor_helpers.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # Another group of helpers for changing the cursor position are the pad methods.
 # They accept a numeric value and a block. <code>pad</code> will use the numeric
 # value to move the cursor down both before and after the block content.
@@ -8,33 +8,32 @@
 #
 # <code>float</code> is a method for not changing the cursor. Pass it a block
 # and the cursor will remain on the same place when the block returns.
-#
-require File.expand_path(File.join(File.dirname(__FILE__),
-                                   %w[.. example_helper]))
+
+require_relative '../example_helper'
 
 filename = File.basename(__FILE__).gsub('.rb', '.pdf')
 Prawn::ManualBuilder::Example.generate(filename) do
   stroke_horizontal_rule
-  pad(20) { text "Text padded both before and after." }
+  pad(20) { text 'Text padded both before and after.' }
 
   stroke_horizontal_rule
-  pad_top(20) { text "Text padded on the top." }
+  pad_top(20) { text 'Text padded on the top.' }
 
   stroke_horizontal_rule
-  pad_bottom(20) { text "Text padded on the bottom." }
+  pad_bottom(20) { text 'Text padded on the bottom.' }
 
   stroke_horizontal_rule
   move_down 30
 
-  text "Text written before the float block."
+  text 'Text written before the float block.'
 
   float do
     move_down 30
-    bounding_box([0, cursor], :width => 200) do
-      text "Text written inside the float block."
+    bounding_box([0, cursor], width: 200) do
+      text 'Text written inside the float block.'
       stroke_bounds
     end
   end
 
-  text "Text written after the float block."
+  text 'Text written after the float block.'
 end

data/manual/basic_concepts/view.rb

@@ -1,20 +1,26 @@
-# encoding: UTF-8
+# frozen_string_literal: true
+
+# The recommended way to extend Prawn's functionality is to include the
+# <code>Prawn::View</code> mixin in your own class, which will make all
+# <code>Prawn::Document</code> methods available to your custom objects.
 #
-# To create a custom class that extends Prawn's functionality,
-# use the <code>Prawn::View</code> mixin. This approach is safer than creating
-# subclasses of <code>Prawn::Document</code> while being just as convenient.
+# This approach is preferred over inheriting from
+# <code>Prawn::Document</code>, as your state will be kept completely separate
+# from <code>Prawn::Document</code>'s, thus avoiding accidental method
+# collisions.
 #
-# By using this mixin, your state will be kept completely separate
-# from <code>Prawn::Document</code>'s state, and you will avoid accidental method
-# collisions within <code>Prawn::Document</code>.
+# Note that <code>Prawn::View</code> lazily instantiates a
+# <code>Prawn::Document</code> with default initialization settings, such as
+# page size, layout, margins, etc.
 #
-# To build custom classes that make use of other custom classes,
-# you can define a method named <code>document()</code> that returns
-# any object that acts similar to a <code>Prawn::Document</code>
-# object. <code>Prawn::View</code> will then direct all delegated
-# calls to that object instead.
+# By defining your own <code>document</code> method, as shown in the example,
+# you will be able to override those settings and initialize a
+# <code>Prawn::Document</code> to your heart's content. This method will be
+# called repeatedly by <code>Prawn::View</code>, so be sure to memoize the
+# object by assigning it to an instance variable via the <code>||=</code>
+# operator.
 
-require_relative "../example_helper"
+require_relative '../example_helper'
 
 class Greeter
   include Prawn::View
@@ -28,15 +34,15 @@ class Greeter
   end
 
   def say_goodbye
-    font("Courier") do
+    font('Courier') do
       text "Goodbye, #{@name}!"
     end
   end
 end
 
-greeter = Greeter.new("Gregory")
+greeter = Greeter.new('Gregory')
 
 greeter.say_hello
 greeter.say_goodbye
 
-greeter.save_as("greetings.pdf")
+greeter.save_as('greetings.pdf')

data/manual/bounding_box/bounding_box.rb

@@ -1,36 +1,41 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # Examples for bounding boxes.
-#
-require File.expand_path(File.join(File.dirname(__FILE__),
-                                   %w[.. example_helper]))
 
-Prawn::ManualBuilder::Example.generate("bounding_box.pdf", :page_size => "FOLIO") do
-  package "bounding_box" do |p|
-    p.section "Basics" do |s|
-      s.example "creation"
-      s.example "bounds"
+require_relative '../example_helper'
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename, page_size: 'FOLIO') do
+  package 'bounding_box' do |p|
+    p.section 'Basics' do |s|
+      s.example 'creation'
+      s.example 'bounds'
     end
 
-    p.section "Advanced" do |s|
-      s.example "stretchy"
-      s.example "nesting"
-      s.example "indentation"
-      s.example "canvas"
-      s.example "russian_boxes"
+    p.section 'Advanced' do |s|
+      s.example 'stretchy'
+      s.example 'nesting'
+      s.example 'indentation'
+      s.example 'canvas'
+      s.example 'russian_boxes'
     end
 
     p.intro do
-      prose("Bounding boxes are the basic containers for structuring the content flow. Even being low level building blocks sometimes their simplicity is very welcome.
+      prose <<-TEXT
+        Bounding boxes are the basic containers for structuring the content
+        flow. Even being low level building blocks sometimes their simplicity is
+        very welcome.
 
-      The examples show:")
+        The examples show:
+      TEXT
 
-      list( "How to create bounding boxes with specific dimensions",
-            "How to inspect the current bounding box for its coordinates",
-            "Stretchy bounding boxes",
-            "Nested bounding boxes",
-            "Indent blocks"
-          )
+      list(
+        'How to create bounding boxes with specific dimensions',
+        'How to inspect the current bounding box for its coordinates',
+        'Stretchy bounding boxes',
+        'Nested bounding boxes',
+        'Indent blocks'
+      )
     end
   end
 end

data/manual/bounding_box/bounds.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # The <code>bounds</code> method returns the current bounding box. This is
 # useful because the <code>Prawn::BoundingBox</code> exposes some nice boundary
 # helpers.
@@ -16,9 +16,8 @@
 #
 # The following snippet shows the boundaries for the margin box side by side
 # with the boundaries for a custom bounding box.
-#
-require File.expand_path(File.join(File.dirname(__FILE__),
-                                   %w[.. example_helper]))
+
+require_relative '../example_helper'
 
 filename = File.basename(__FILE__).gsub('.rb', '.pdf')
 Prawn::ManualBuilder::Example.generate(filename) do
@@ -30,18 +29,18 @@ Prawn::ManualBuilder::Example.generate(filename) do
 
     move_down 10
 
-    text "absolute top: #{sprintf "%.2f", bounds.absolute_top}"
-    text "absolute bottom: #{sprintf "%.2f", bounds.absolute_bottom}"
-    text "absolute left: #{sprintf "%.2f", bounds.absolute_left}"
-    text "absolute right: #{sprintf "%.2f", bounds.absolute_right}"
+    text "absolute top: #{bounds.absolute_top.to_f.round(2)}"
+    text "absolute bottom: #{bounds.absolute_bottom.to_f.round(2)}"
+    text "absolute left: #{bounds.absolute_left.to_f.round(2)}"
+    text "absolute right: #{bounds.absolute_right.to_f.round(2)}"
   end
 
-  text "Margin box bounds:"
+  text 'Margin box bounds:'
   move_down 5
   print_coordinates
 
-  bounding_box([250, cursor + 140], :width => 200, :height => 150) do
-    text "This bounding box bounds:"
+  bounding_box([250, cursor + 140], width: 200, height: 150) do
+    text 'This bounding box bounds:'
     move_down 5
     print_coordinates
     transparent(0.5) { stroke_bounds }

data/manual/bounding_box/canvas.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # The origin example already mentions that a new document already comes with
 # a margin box whose bottom left corner is used as the origin for calculating
 # coordinates.
@@ -9,9 +9,8 @@
 # box mapped to the absolute coordinates and evaluating the code inside it.
 #
 # The following snippet draws a circle on each of the four absolute corners.
-#
-require File.expand_path(File.join(File.dirname(__FILE__),
-                                   %w[.. example_helper]))
+
+require_relative '../example_helper'
 
 filename = File.basename(__FILE__).gsub('.rb', '.pdf')
 Prawn::ManualBuilder::Example.generate(filename) do

data/manual/bounding_box/creation.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # If you've read the basic concepts examples you probably know that the origin
 # of a page is on the bottom left corner and that the content flows from top to
 # bottom.
@@ -9,14 +9,13 @@
 # A bounding box can be created with the <code>bounding_box</code> method. Just
 # provide the top left corner, a required <code>:width</code> option and an
 # optional <code>:height</code>.
-#
-require File.expand_path(File.join(File.dirname(__FILE__),
-                                   %w[.. example_helper]))
+
+require_relative '../example_helper'
 
 filename = File.basename(__FILE__).gsub('.rb', '.pdf')
 Prawn::ManualBuilder::Example.generate(filename) do
-  bounding_box([200, cursor - 100], :width => 200, :height => 100) do
-    text "Just your regular bounding box"
+  bounding_box([200, cursor - 100], width: 200, height: 100) do
+    text 'Just your regular bounding box'
 
     transparent(0.5) { stroke_bounds }
   end

data/manual/bounding_box/indentation.rb

@@ -1,43 +1,42 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # Sometimes you just need to indent a portion of the contents of a bounding box,
 # and using a nested bounding box is pure overkill. The <code>indent</code>
 # method is what you might need.
 #
 # Just provide a number for it to indent all content generated inside the
 # block.
-#
-require File.expand_path(File.join(File.dirname(__FILE__),
-                                   %w[.. example_helper]))
+
+require_relative '../example_helper'
 
 filename = File.basename(__FILE__).gsub('.rb', '.pdf')
 Prawn::ManualBuilder::Example.generate(filename) do
-  text "No indentation on the margin box."
+  text 'No indentation on the margin box.'
   indent(20) do
-    text "Some indentation inside an indent block."
+    text 'Some indentation inside an indent block.'
   end
   move_down 20
 
-  bounding_box([50, cursor], :width => 400, :height => cursor) do
+  bounding_box([50, cursor], width: 400, height: cursor) do
     transparent(0.5) { stroke_bounds }
 
     move_down 10
-    text "No indentation inside this bounding box."
+    text 'No indentation inside this bounding box.'
     indent(40) do
-      text "Inside an indent block. And so is this horizontal line:"
+      text 'Inside an indent block. And so is this horizontal line:'
 
       stroke_horizontal_rule
     end
     move_down 10
-    text "No indentation"
+    text 'No indentation'
 
     move_down 20
     indent(60) do
-      text "Another indent block."
+      text 'Another indent block.'
 
-      bounding_box([0, cursor], :width => 200) do
-        text "Note that this bounding box coordinates are relative to the " +
-             "indent block"
+      bounding_box([0, cursor], width: 200) do
+        text 'Note that this bounding box coordinates are relative to the ' \
+          'indent block'
 
         transparent(0.5) { stroke_bounds }
       end

data/manual/bounding_box/nesting.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # Normally when we provide the top left corner of a bounding box we
 # express the coordinates relative to the margin box. This is not the
 # case when we have nested bounding boxes. Once nested the inner bounding box
@@ -8,9 +8,8 @@
 # This example shows some nested bounding boxes with fixed and stretchy heights.
 # Note how the <code>cursor</code> method returns coordinates relative to
 # the current bounding box.
-#
-require File.expand_path(File.join(File.dirname(__FILE__),
-                                   %w[.. example_helper]))
+
+require_relative '../example_helper'
 
 filename = File.basename(__FILE__).gsub('.rb', '.pdf')
 Prawn::ManualBuilder::Example.generate(filename) do
@@ -20,26 +19,34 @@ Prawn::ManualBuilder::Example.generate(filename) do
   end
 
   gap = 20
-  bounding_box([50, cursor], :width => 400, :height => 200) do
-    box_content("Fixed height")
+  bounding_box([50, cursor], width: 400, height: 200) do
+    box_content('Fixed height')
 
-    bounding_box([gap, cursor - gap], :width => 300) do
-      text "Stretchy height"
+    bounding_box([gap, cursor - gap], width: 300) do
+      text 'Stretchy height'
 
-      bounding_box([gap, bounds.top - gap], :width => 100) do
-        text "Stretchy height"
-        transparent(0.5) { dash(1); stroke_bounds; undash }
+      bounding_box([gap, bounds.top - gap], width: 100) do
+        text 'Stretchy height'
+        transparent(0.5) do
+          dash(1)
+          stroke_bounds
+          undash
+        end
       end
 
-      bounding_box([gap * 7, bounds.top - gap], :width => 100, :height => 50) do
-        box_content("Fixed height")
+      bounding_box([gap * 7, bounds.top - gap], width: 100, height: 50) do
+        box_content('Fixed height')
       end
 
-      transparent(0.5) { dash(1); stroke_bounds; undash }
+      transparent(0.5) do
+        dash(1)
+        stroke_bounds
+        undash
+      end
     end
 
-    bounding_box([gap, cursor - gap], :width => 300, :height => 50) do
-      box_content("Fixed height")
+    bounding_box([gap, cursor - gap], width: 300, height: 50) do
+      box_content('Fixed height')
     end
   end
 end