prawn 2.1.0 → 2.2.0

data/manual/basic_concepts/view.rb

@@ -1,20 +1,24 @@
-# encoding: UTF-8
+# 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 +32,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,39 @@
-# encoding: utf-8
-#
 # 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 <<-END
+        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:
+      END
 
-      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,3 @@
-# encoding: utf-8
-#
 # 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 +14,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 +27,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: #{format '%.2f', bounds.absolute_top}"
+    text "absolute bottom: #{format '%.2f', bounds.absolute_bottom}"
+    text "absolute left: #{format '%.2f', bounds.absolute_left}"
+    text "absolute right: #{format '%.2f', bounds.absolute_right}"
   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,3 @@
-# encoding: utf-8
-#
 # 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 +7,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,3 @@
-# encoding: utf-8
-#
 # 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 +7,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,40 @@
-# encoding: utf-8
-#
 # 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,3 @@
-# encoding: utf-8
-#
 # 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 +6,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 +17,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

data/manual/bounding_box/russian_boxes.rb

@@ -1,11 +1,8 @@
-# encoding: utf-8
-#
 # This example is mostly just for fun, and shows how nested bounding boxes
 # can simplify calculations. See the "Bounding Box" section of the manual
 # for more basic uses.
-#
-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
@@ -22,10 +19,12 @@ Prawn::ManualBuilder::Example.generate(filename) do
   def recurse_bounding_box(max_depth = 4, depth = 1)
     width = (bounds.width - 15) / 2
     height = (bounds.height - 15) / 2
-    left_top_corners = combine([5, bounds.right - width - 5],
-                               [bounds.top - 5, height + 5])
+    left_top_corners = combine(
+      [5, bounds.right - width - 5],
+      [bounds.top - 5, height + 5]
+    )
     left_top_corners.each do |lt|
-      bounding_box(lt, :width => width, :height => height) do
+      bounding_box(lt, width: width, height: height) do
         stroke_bounds
         recurse_bounding_box(max_depth, depth + 1) if depth < max_depth
       end
@@ -33,7 +32,7 @@ Prawn::ManualBuilder::Example.generate(filename) do
   end
 
   # Set up a bbox from the dashed line to the bottom of the page
-  bounding_box([0, cursor], :width => bounds.width, :height => cursor) do
+  bounding_box([0, cursor], width: bounds.width, height: cursor) do
     recurse_bounding_box
   end
 end

data/manual/bounding_box/stretchy.rb

@@ -1,29 +1,26 @@
-# encoding: utf-8
-#
 # Bounding Boxes accept an optional <code>:height</code> parameter. Unless it
 # is provided the bounding box will be stretchy. It will expand the height to
 # fit all content generated inside it.
-#
-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
   y_position = cursor
-  bounding_box([0, y_position], :width => 200, :height => 100) do
-    text "This bounding box has a height of 100. If this text gets too large " +
-         "it will flow to the next page."
+  bounding_box([0, y_position], width: 200, height: 100) do
+    text 'This bounding box has a height of 100. If this text gets too large ' \
+      'it will flow to the next page.'
 
     transparent(0.5) { stroke_bounds }
   end
 
-  bounding_box([300, y_position], :width => 200) do
-    text "This bounding box has variable height. No matter how much text is " +
-         "written here, the height will expand to fit."
+  bounding_box([300, y_position], width: 200) do
+    text 'This bounding box has variable height. No matter how much text is ' \
+      'written here, the height will expand to fit.'
 
-    text " _" * 100
+    text ' _' * 100
 
-    text " *" * 100
+    text ' *' * 100
 
     transparent(0.5) { stroke_bounds }
   end

data/manual/contents.rb

@@ -1,29 +1,33 @@
-# encoding: utf-8
-#
 # Generates the Prawn by example manual.
 
-require_relative "example_helper"
+require_relative 'example_helper'
 
-Encoding.default_external = Encoding::UTF_8
+def prawn_manual_document
+  old_default_external_encoding = Encoding.default_external
+  Encoding.default_external = Encoding::UTF_8
 
-Prawn::ManualBuilder::Example.generate("manual.pdf",
-                                       :skip_page_creation => true,
-                                       :page_size => "FOLIO") do
-  load_page "", "cover"
-  load_page "", "how_to_read_this_manual"
+  Prawn::ManualBuilder::Example.new(
+    skip_page_creation: true,
+    page_size: 'FOLIO'
+  ) do
+    load_page '', 'cover'
+    load_page '', 'how_to_read_this_manual'
 
-  # Core chapters
-  load_package "basic_concepts"
-  load_package "graphics"
-  load_package "text"
-  load_package "bounding_box"
+    # Core chapters
+    load_package 'basic_concepts'
+    load_package 'graphics'
+    load_package 'text'
+    load_package 'bounding_box'
 
-  # Remaining chapters
-  load_package "layout"
-  load_page "", "table"
-  load_package "images"
-  load_package "document_and_page_options"
-  load_package "outline"
-  load_package "repeatable_content"
-  load_package "security"
+    # Remaining chapters
+    load_package 'layout'
+    load_page '', 'table'
+    load_package 'images'
+    load_package 'document_and_page_options'
+    load_package 'outline'
+    load_package 'repeatable_content'
+    load_package 'security'
+  end
+ensure
+  Encoding.default_external = old_default_external_encoding
 end