prawn 0.13.0 → 2.4.0

data/lib/prawn.rb

@@ -1,32 +1,17 @@
+# frozen_string_literal: true
+
 # Welcome to Prawn, the best PDF Generation library ever.
 # This documentation covers user level functionality.
 #
-# Those looking to contribute code or write extensions should look
-# into the lib/prawn/core/* source tree.
-#
-%w[ttfunk/lib].each do |dep|
-  $LOAD_PATH.unshift(File.dirname(__FILE__) + "/../../vendor/#{dep}")
-end
-
-begin
-  require 'ttfunk'
-rescue LoadError
-  puts "Failed to load ttfunk. If you are running Prawn from git:"
-  puts "  git submodule init"
-  puts "  git submodule update"
-  exit
-end
+require 'set'
 
-require "set"
+require 'ttfunk'
+require 'pdf/core'
 
 module Prawn
-  VERSION = "0.13.0"
-
-  extend self
-
   file = __FILE__
   file = File.readlink(file) if File.symlink?(file)
-  dir  = File.dirname(file)
+  dir = File.dirname(file)
 
   # The base source directory for Prawn as installed on the system
   #
@@ -34,7 +19,9 @@ module Prawn
   BASEDIR = File.expand_path(File.join(dir, '..'))
   DATADIR = File.expand_path(File.join(dir, '..', 'data'))
 
-  # Whe set to true, Prawn will verify hash options to ensure only valid keys
+  FLOAT_PRECISION = 1.0e-9
+
+  # When set to true, Prawn will verify hash options to ensure only valid keys
   # are used.  Off by default.
   #
   # Example:
@@ -43,62 +30,49 @@ module Prawn
   #   Detected unknown option(s): [:tomato]
   #   Accepted options are: [:page_size, :page_layout, :left_margin, ...]
   #
+  # @private
   attr_accessor :debug
 
-  def verify_options(accepted, actual) #:nodoc:
+  module_function :debug, :debug=
+
+  module_function
+
+  # @private
+  def verify_options(accepted, actual)
     return unless debug || $DEBUG
-    unless (act=Set[*actual.keys]).subset?(acc=Set[*accepted])
+
+    unless (act = Set[*actual.keys]).subset?(acc = Set[*accepted])
       raise Prawn::Errors::UnknownOption,
-        "\nDetected unknown option(s): #{(act - acc).to_a.inspect}\n" <<
+        "\nDetected unknown option(s): #{(act - acc).to_a.inspect}\n" \
         "Accepted options are: #{accepted.inspect}"
     end
     yield if block_given?
   end
-
-  module Configurable #:nodoc:
-    def configuration(*args)
-      @config ||= Marshal.load(Marshal.dump(default_configuration))
-      if Hash === args[0]
-        @config.update(args[0])
-      elsif args.length > 1
-        @config.values_at(*args)
-      elsif args.length == 1
-        @config[args[0]]
-      else
-        @config
-      end
-    end
-
-    alias_method :C, :configuration
-  end
 end
 
-require_relative "prawn/compatibility"
-require_relative "prawn/errors"
-
-require_relative "pdf/core"
-
-require_relative "prawn/utilities"
-require_relative "prawn/text"
-require_relative "prawn/graphics"
-require_relative "prawn/images"
-require_relative "prawn/images/image"
-require_relative "prawn/images/jpg"
-require_relative "prawn/images/png"
-require_relative "prawn/stamp"
-require_relative "prawn/soft_mask"
-require_relative "prawn/security"
-require_relative "prawn/document"
-require_relative "prawn/font"
-require_relative "prawn/encoding"
-require_relative "prawn/measurements"
-require_relative "prawn/repeater"
-require_relative "prawn/outline"
-require_relative "prawn/layout"
-
-require_relative "prawn/image_handler"
-
-
+require_relative 'prawn/version'
+
+require_relative 'prawn/errors'
+
+require_relative 'prawn/utilities'
+require_relative 'prawn/text'
+require_relative 'prawn/graphics'
+require_relative 'prawn/images'
+require_relative 'prawn/images/image'
+require_relative 'prawn/images/jpg'
+require_relative 'prawn/images/png'
+require_relative 'prawn/stamp'
+require_relative 'prawn/soft_mask'
+require_relative 'prawn/security'
+require_relative 'prawn/transformation_stack'
+require_relative 'prawn/document'
+require_relative 'prawn/font'
+require_relative 'prawn/measurements'
+require_relative 'prawn/repeater'
+require_relative 'prawn/outline'
+require_relative 'prawn/grid'
+require_relative 'prawn/view'
+require_relative 'prawn/image_handler'
 
 Prawn.image_handler.register(Prawn::Images::PNG)
 Prawn.image_handler.register(Prawn::Images::JPG)

data/manual/basic_concepts/adding_pages.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # A PDF document is a collection of pages. When we create a new document be it
 # with <code>Document.new</code> or on a <code>Document.generate</code> block
 # one initial page is created for us.
@@ -12,16 +12,15 @@
 #
 # Just use the <code>start_new_page</code> method and a shiny new page will be
 # created for you just like in the following snippet.
-#
-require File.expand_path(File.join(File.dirname(__FILE__),
-                                   %w[.. example_helper]))
+
+require_relative '../example_helper'
 
 filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::Example.generate(filename) do
-  text "We are still on the initial page for this example. Now I'll ask " +
-       "Prawn to gently start a new page. Please follow me to the next page."
-  
+Prawn::ManualBuilder::Example.generate(filename) do
+  text "We are still on the initial page for this example. Now I'll ask " \
+    'Prawn to gently start a new page. Please follow me to the next page.'
+
   start_new_page
-  
+
   text "See. We've left the previous page behind."
 end

data/manual/basic_concepts/basic_concepts.rb

@@ -1,34 +1,43 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # Examples for Prawn basic concepts.
 #
-require File.expand_path(File.join(File.dirname(__FILE__),
-                                   %w[.. example_helper]))
 
-Prawn::Example.generate("basic_concepts.pdf", :page_size => "FOLIO") do
-  
-  package "basic_concepts" do |p|
-    
-    p.example "creation", :eval_source => false, :full_source => true
-    p.example "origin"
-    p.example "cursor"
-    p.example "other_cursor_helpers"
-    p.example "adding_pages"
-    p.example "measurement"
-    
+require_relative '../example_helper'
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename, page_size: 'FOLIO') do
+  package 'basic_concepts' do |p|
+    p.example 'creation', eval_source: false, full_source: true
+    p.example 'origin'
+    p.example 'cursor'
+    p.example 'other_cursor_helpers'
+    p.example 'adding_pages'
+    p.example 'measurement'
+    p.example 'view', eval_source: false, full_source: true
+
     p.intro do
-      prose("This chapter covers the minimum amount of functionality you'll need to start using Prawn.
+      prose <<-TEXT
+        This chapter covers the minimum amount of functionality you'll need to
+        start using Prawn.
 
-      If you are new to Prawn this is the first chapter to read. Once you are comfortable with the concepts shown here you might want to check the Basics section of the Graphics, Bounding Box and Text sections.
+        If you are new to Prawn this is the first chapter to read. Once you are
+        comfortable with the concepts shown here you might want to check the
+        Basics section of the Graphics, Bounding Box and Text sections.
 
-      The examples show:")
+        The examples show:
+      TEXT
 
-      list( "How to create new pdf documents in every possible way",
-            "Where the origin for the document coordinates is. What are Bounding Boxes and how they interact with the origin",
-            "How the cursor behaves",
-            "How to start new pages",
-            "What the base unit for measurement and coordinates is and how to use other convenient measures"
-          )
+      list(
+        'How to create new pdf documents in every possible way',
+        'Where the origin for the document coordinates is. What are Bounding '\
+          'Boxes and how they interact with the origin',
+        'How the cursor behaves',
+        'How to start new pages',
+        'What the base unit for measurement and coordinates is and how to use '\
+          'other convenient measures',
+        "How to build custom view objects that use Prawn's DSL"
+      )
     end
   end
 end

data/manual/basic_concepts/creation.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # There are three ways to create a PDF Document in Prawn: creating a new
 # <code>Prawn::Document</code> instance, or using the
 # <code>Prawn::Document.generate</code> method with and without block arguments.
@@ -19,21 +19,20 @@
 # The generate method without block arguments requires
 # less typing and defines and renders the pdf document in one shot.
 # Almost all of the examples are coded this way.
-#
-require File.expand_path(File.join(File.dirname(__FILE__),
-                                   %w[.. example_helper]))
+
+require_relative '../example_helper'
 
 # Assignment
 pdf = Prawn::Document.new
-pdf.text "Hello World"
-pdf.render_file "assignment.pdf"
+pdf.text 'Hello World'
+pdf.render_file 'assignment.pdf'
 
 # Implicit Block
-Prawn::Document.generate("implicit.pdf") do
-  text "Hello World"
+Prawn::Document.generate('implicit.pdf') do
+  text 'Hello World'
 end
 
 # Explicit Block
-Prawn::Document.generate("explicit.pdf") do |pdf|
-  pdf.text "Hello World"
+Prawn::Document.generate('explicit.pdf') do |pdf|
+  pdf.text 'Hello World'
 end

data/manual/basic_concepts/cursor.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # We normally write our documents from top to bottom and it is no different with
 # Prawn. Even if the origin is on the bottom left corner we still fill the page
 # from the top to the bottom. In other words the cursor for inserting content
@@ -11,23 +11,22 @@
 # The following snippet shows how the cursor behaves when we add some text to
 # the page and demonstrates some of the helpers to manage the cursor position.
 # The <code>cursor</code> method returns the current cursor position.
-#
-require File.expand_path(File.join(File.dirname(__FILE__),
-                                   %w[.. example_helper]))
+
+require_relative '../example_helper'
 
 filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::Example.generate(filename) do
+Prawn::ManualBuilder::Example.generate(filename) do
   stroke_axis
-  
+
   text "the cursor is here: #{cursor}"
   text "now it is here: #{cursor}"
-  
+
   move_down 200
   text "on the first move the cursor went down to: #{cursor}"
-  
+
   move_up 100
   text "on the second move the cursor went up to: #{cursor}"
-  
+
   move_cursor_to 50
   text "on the last move the cursor went directly to: #{cursor}"
 end

data/manual/basic_concepts/measurement.rb

@@ -1,25 +1,24 @@
-# 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.
 #
-# There is no need to waste time converting this measures. Prawn provides
+# There is no need to waste time converting this measure. Prawn provides
 # helpers for converting from other measurements
 # to PDF Points.
 #
 # 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::Example.generate(filename) do
-  require "prawn/measurement_extensions"
-  
-  [:mm, :cm, :dm, :m, :in, :yd, :ft].each do |measurement|
-    text "1 #{measurement} in PDF Points: #{1.send(measurement)} pt"
+Prawn::ManualBuilder::Example.generate(filename) do
+  require 'prawn/measurement_extensions'
+
+  %i[mm cm dm m in yd ft].each do |measurement|
+    text "1 #{measurement} in PDF Points: #{1.public_send(measurement)} pt"
     move_down 5.mm
   end
 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,17 +21,16 @@
 #
 # 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::Example.generate(filename) do
+Prawn::ManualBuilder::Example.generate(filename) do
   stroke_axis
-  
+
   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::Example.generate(filename) do
+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

@@ -0,0 +1,48 @@
+# 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.
+#
+# 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.
+#
+# Note that <code>Prawn::View</code> lazily instantiates a
+# <code>Prawn::Document</code> with default initialization settings, such as
+# page size, layout, margins, etc.
+#
+# 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'
+
+class Greeter
+  include Prawn::View
+
+  def initialize(name)
+    @name = name
+  end
+
+  def say_hello
+    text "Hello, #{@name}!"
+  end
+
+  def say_goodbye
+    font('Courier') do
+      text "Goodbye, #{@name}!"
+    end
+  end
+end
+
+greeter = Greeter.new('Gregory')
+
+greeter.say_hello
+greeter.say_goodbye
+
+greeter.save_as('greetings.pdf')

data/manual/bounding_box/bounding_box.rb

@@ -1,39 +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::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,7 +1,7 @@
-# encoding: utf-8
-# 
+# frozen_string_literal: true
+
 # The <code>bounds</code> method returns the current bounding box. This is
-# useful because the <code>Prawn::BoundinBox</code> exposes some nice boundary
+# useful because the <code>Prawn::BoundingBox</code> exposes some nice boundary
 # helpers.
 #
 # <code>top</code>, <code>bottom</code>, <code>left</code> and
@@ -16,32 +16,31 @@
 #
 # 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::Example.generate(filename) do
+Prawn::ManualBuilder::Example.generate(filename) do
   def print_coordinates
     text "top: #{bounds.top}"
     text "bottom: #{bounds.bottom}"
     text "left: #{bounds.left}"
     text "right: #{bounds.right}"
-    
+
     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,16 +9,15 @@
 # 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::Example.generate(filename) do
+Prawn::ManualBuilder::Example.generate(filename) do
   canvas do
-    fill_circle [bounds.left, bounds.top],     30
-    fill_circle [bounds.right, bounds.top],    30
+    fill_circle [bounds.left, bounds.top], 30
+    fill_circle [bounds.right, bounds.top], 30
     fill_circle [bounds.right, bounds.bottom], 30
-    fill_circle [0, 0],                        30
+    fill_circle [0, 0], 30
   end
 end