prawn 0.13.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ad2fdbe5f0c7d9075d0a6467217a996304aa4983
-  data.tar.gz: 6db5219bdb341f2c8d36c3cc0aca48720adbdccc
+SHA256:
+  metadata.gz: d64c2da1e4be48e40f4fa6fa4de35e04c75debf0119e8c59b3fba9d944c112db
+  data.tar.gz: 393bbdd1a5df657d5c6190d4bd10ecd7353522e714b2f60c8d9c5f70e5bc1ce9
 SHA512:
-  metadata.gz: c2795eaa023f044fdf99b91f79a4e56f181c8dcb13fd73112dcf181156234230117e17221521634c728e60c92a7f05a607f16cec47cd72eff9a77995e91f750f
-  data.tar.gz: cdf2c886e7bea9946289a11fa1f33c4574884ca65d2eebbaec6967016bc31aee008a9048fccecb73756a4950a6b4e686c838ddbf5e3c3c258bd1dd2ed6fea379
+  metadata.gz: c4980639ca24796d577be790ed0f6fa85c985f1a6eb147e4c5db1df261c5d50afe8a466f06b65588b71a897e22e8d2b7b01daceed1714f6164124057154d2d28
+  data.tar.gz: e0fd560d4a80f2827736d599266bcb2e2fe19abedcde639520fba8bd19a2f12fe2cf0e8a60a91b87dbac4336d25c680f94b2341e5f9ce3d6d24f2e65f24e24a3

data/.yardopts

@@ -0,0 +1,10 @@
+--charset UTF-8
+--main README.md
+--title 'Prawn Documentation'
+--no-private
+-
+CONTRIBUTING.md
+COPYING
+LICENSE
+README.md
+CHANGELOG.md

data/GPLv2

@@ -1,12 +1,12 @@
-		    GNU GENERAL PUBLIC LICENSE
-		       Version 2, June 1991
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
 
- Copyright (C) 1989, 1991 Free Software Foundation, Inc.
-     59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  Everyone is permitted to copy and distribute verbatim copies
  of this license document, but changing it is not allowed.
 
-			    Preamble
+                            Preamble
 
   The licenses for most software are designed to take away your
 freedom to share and change it.  By contrast, the GNU General Public
@@ -15,7 +15,7 @@ software--to make sure the software is free for all its users.  This
 General Public License applies to most of the Free Software
 Foundation's software and to any other program whose authors commit to
 using it.  (Some other Free Software Foundation software is covered by
-the GNU Library General Public License instead.)  You can apply it to
+the GNU Lesser General Public License instead.)  You can apply it to
 your programs, too.
 
   When we speak of free software, we are referring to freedom, not
@@ -55,8 +55,8 @@ patent must be licensed for everyone's free use or not licensed at all.
 
   The precise terms and conditions for copying, distribution and
 modification follow.
-
-		    GNU GENERAL PUBLIC LICENSE
+
+                    GNU GENERAL PUBLIC LICENSE
    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
 
   0. This License applies to any program or other work which contains
@@ -110,7 +110,7 @@ above, provided that you also meet all of these conditions:
     License.  (Exception: if the Program itself is interactive but
     does not normally print such an announcement, your work based on
     the Program is not required to print an announcement.)
-
+
 These requirements apply to the modified work as a whole.  If
 identifiable sections of that work are not derived from the Program,
 and can be reasonably considered independent and separate works in
@@ -168,7 +168,7 @@ access to copy from a designated place, then offering equivalent
 access to copy the source code from the same place counts as
 distribution of the source code, even though third parties are not
 compelled to copy the source along with the object code.
-
+
   4. You may not copy, modify, sublicense, or distribute the Program
 except as expressly provided under this License.  Any attempt
 otherwise to copy, modify, sublicense or distribute the Program is
@@ -225,7 +225,7 @@ impose that choice.
 
 This section is intended to make thoroughly clear what is believed to
 be a consequence of the rest of this License.
-
+
   8. If the distribution and/or use of the Program is restricted in
 certain countries either by patents or by copyrighted interfaces, the
 original copyright holder who places the Program under this License
@@ -255,7 +255,7 @@ make exceptions for this.  Our decision will be guided by the two goals
 of preserving the free status of all derivatives of our free software and
 of promoting the sharing and reuse of software generally.
 
-			    NO WARRANTY
+                            NO WARRANTY
 
   11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
@@ -277,9 +277,9 @@ YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
 POSSIBILITY OF SUCH DAMAGES.
 
-		     END OF TERMS AND CONDITIONS
-
-	    How to Apply These Terms to Your New Programs
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
 
   If you develop a new program, and you want it to be of the greatest
 possible use to the public, the best way to achieve this is to make it
@@ -303,17 +303,16 @@ the "copyright" line and a pointer to where the full notice is found.
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
 
-    You should have received a copy of the GNU General Public License
-    along with this program; if not, write to the Free Software
-    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
-
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, write to the Free Software Foundation, Inc.,
+    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
 Also add information on how to contact you by electronic and paper mail.
 
 If the program is interactive, make it output a short notice like this
 when it starts in an interactive mode:
 
-    Gnomovision version 69, Copyright (C) year  name of author
+    Gnomovision version 69, Copyright (C) year name of author
     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
     This is free software, and you are welcome to redistribute it
     under certain conditions; type `show c' for details.
@@ -336,5 +335,5 @@ necessary.  Here is a sample; alter the names:
 This General Public License does not permit incorporating your program into
 proprietary programs.  If your program is a subroutine library, you may
 consider it more useful to permit linking proprietary applications with the
-library.  If this is what you want to do, use the GNU Library General
+library.  If this is what you want to do, use the GNU Lesser General
 Public License instead of this License.

data/Gemfile

@@ -1,18 +1,5 @@
-source "https://rubygems.org"
+# frozen_string_literal: true
 
-gem "ttfunk", "~>1.0.3"
-gem "pdf-reader", "~> 1.2"
-gem "ruby-rc4"
-gem "afm"
+source 'https://rubygems.org'
 
-group :development do
-  gem "coderay", "~> 1.0.7"
-  gem "rdoc"
-end
-
-group :test do
-  gem "pdf-inspector", "~> 1.1.0", :require => "pdf/inspector"
-  gem "rspec"
-  gem "mocha", :require => false
-  gem "rake"
-end
+gemspec

data/Rakefile

@@ -1,47 +1,25 @@
-require "bundler"
-Bundler.setup
+# frozen_string_literal: true
 
-require 'rake'
-require 'rspec/core/rake_task'
-require 'rdoc/task'
-require 'rubygems/package_task'
+GEMSPEC = File.expand_path('prawn.gemspec', __dir__)
+require 'prawn/dev/tasks'
 
-task :default => [:spec]
-
-desc "Run all rspec files"
-RSpec::Core::RakeTask.new("spec") do |c|
-  c.rspec_opts = "-t ~unresolved"
-end
-
-desc "Show library's code statistics"
-task :stats do
-  require 'code_statistics'
-  CodeStatistics::TEST_TYPES << "Specs"
-  CodeStatistics.new( ["Prawn", "lib"],
-                      ["Specs", "spec"] ).to_s
-end
-
-desc "genrates documentation"
-RDoc::Task.new do |rdoc|
-  rdoc.rdoc_files.include( "README.md",
-                           "COPYING",
-                           "LICENSE",
-                           "lib/" )
-  rdoc.main     = "README.md"
-  rdoc.rdoc_dir = "doc/html"
-  rdoc.title    = "Prawn Documentation"
-end
+task default: %i[spec rubocop]
 
 desc "Generate the 'Prawn by Example' manual"
 task :manual do
-  puts "Building manual..."
-  require File.expand_path(File.join(File.dirname(__FILE__),
-    %w[manual manual manual]))
-  puts "The Prawn manual is available at manual.pdf. Happy Prawning!"
+  puts 'Building manual...'
+  require File.expand_path(File.join(__dir__, %w[manual contents]))
+  prawn_manual_document.render_file('manual.pdf')
+  puts 'The Prawn manual is available at manual.pdf. Happy Prawning!'
 end
 
-spec = Gem::Specification.load "prawn.gemspec"
-Gem::PackageTask.new(spec) do |pkg|
-  pkg.need_zip = true
-  pkg.need_tar = true
+desc 'Run a console with Prawn loaded'
+task :console do
+  require 'irb'
+  require 'irb/completion'
+  require_relative 'lib/prawn'
+  Prawn.debug = true
+
+  ARGV.clear
+  IRB.start
 end

data/lib/prawn/document/bounding_box.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 # bounding_box.rb : Implements a mechanism for shifting the coordinate space
 #
@@ -8,6 +8,7 @@
 
 module Prawn
   class Document
+    # @group Stable API
 
     # :call-seq:
     #   bounding_box(point, options={}, &block)
@@ -154,10 +155,10 @@ module Prawn
     # Of course, if you use canvas, you will be responsible for ensuring that
     # you remain within the printable area of your document.
     #
-    def bounding_box(pt, *args, &block)
+    def bounding_box(point, *args, &block)
       init_bounding_box(block) do |parent_box|
-        pt = map_to_absolute(pt)
-        @bounding_box = BoundingBox.new(self, parent_box, pt, *args)
+        point = map_to_absolute(point)
+        @bounding_box = BoundingBox.new(self, parent_box, point, *args)
       end
     end
 
@@ -169,36 +170,51 @@ module Prawn
     #   end
     #
     def canvas(&block)
-      init_bounding_box(block, :hold_position => true) do |_|
+      init_bounding_box(block, hold_position: true) do |_|
         # Canvas bbox acts like margin_box in that its parent bounds are unset.
-        @bounding_box = BoundingBox.new(self, nil, [0,page.dimensions[3]],
-          :width => page.dimensions[2],
-          :height => page.dimensions[3]
+        @bounding_box = BoundingBox.new(
+          self,
+          nil,
+          [0, page.dimensions[3]],
+          width: page.dimensions[2],
+          height: page.dimensions[3]
         )
       end
     end
 
     private
 
-    def init_bounding_box(user_block, options={}, &init_block)
+    def init_bounding_box(user_block, options = {})
       unless user_block
         raise ArgumentError,
-          "bounding boxes require a block to be drawn within the box"
+          'bounding boxes require a block to be drawn within the box'
       end
 
       parent_box = @bounding_box
 
-      init_block.call(parent_box)
+      original_ypos = y
+
+      yield(parent_box)
 
       self.y = @bounding_box.absolute_top
       user_block.call
+
+      # If the user actions did not modify the y position
+      # restore the original y position before the bounding
+      # box was created.
+
+      if y == @bounding_box.absolute_top
+        self.y = original_ypos
+      end
+
       unless options[:hold_position] || @bounding_box.stretchy?
         self.y = @bounding_box.absolute_bottom
       end
 
-      created_box, @bounding_box = @bounding_box, parent_box
+      created_box = @bounding_box
+      @bounding_box = parent_box
 
-      return created_box
+      created_box
     end
 
     # Low level layout helper that simplifies coordinate math.
@@ -207,30 +223,44 @@ module Prawn
     # is used for.
     #
     class BoundingBox
+      class NoReferenceBounds < StandardError
+        def initialize(message = "Can't find reference bounds: my parent is unset")
+          super
+        end
+      end
 
-      def initialize(document, parent, point, options={}) #:nodoc:
+      # @private
+      def initialize(document, parent, point, options = {})
         unless options[:width]
-          raise ArgumentError, "BoundingBox needs the :width option to be set"
+          raise ArgumentError, 'BoundingBox needs the :width option to be set'
         end
 
         @document = document
         @parent = parent
         @x, @y = point
-        @width, @height = options[:width], options[:height]
+        @width = options[:width]
+        @height = options[:height]
         @total_left_padding = 0
         @total_right_padding = 0
         @stretched_height = nil
       end
 
+      # @private
+
       attr_reader :document, :parent
+
+      # @private
       # The current indentation of the left side of the bounding box.
       attr_reader :total_left_padding
+
+      # @private
       # The current indentation of the right side of the bounding box.
       attr_reader :total_right_padding
 
       # The translated origin (x,y-height) which describes the location
       # of the bottom left corner of the bounding box
       #
+      # @private
       def anchor
         [@x, @y - height]
       end
@@ -245,7 +275,6 @@ module Prawn
         0
       end
 
-
       # Temporarily adjust the @x coordinate to allow for left_padding
       #
       # Example:
@@ -261,7 +290,8 @@ module Prawn
       #    text "indented on both sides"
       #  end
       #
-      def indent(left_padding, right_padding = 0, &block)
+      # @private
+      def indent(left_padding, right_padding = 0)
         add_left_padding(left_padding)
         add_right_padding(right_padding)
         yield
@@ -271,6 +301,7 @@ module Prawn
       end
 
       # Increase the left padding of the bounding box.
+      # @private
       def add_left_padding(left_padding)
         @total_left_padding += left_padding
         @x += left_padding
@@ -278,6 +309,7 @@ module Prawn
       end
 
       # Decrease the left padding of the bounding box.
+      # @private
       def subtract_left_padding(left_padding)
         @total_left_padding -= left_padding
         @x -= left_padding
@@ -285,18 +317,21 @@ module Prawn
       end
 
       # Increase the right padding of the bounding box.
+      # @private
       def add_right_padding(right_padding)
         @total_right_padding += right_padding
         @width -= right_padding
       end
 
       # Decrease the right padding of the bounding box.
+      # @private
       def subtract_right_padding(right_padding)
         @total_right_padding -= right_padding
         @width += right_padding
       end
 
-      # Relative right x-coordinate of the bounding box. (Equal to the box width)
+      # Relative right x-coordinate of the bounding box. (Equal to the box
+      # width)
       #
       # Example, position some text 3 pts from the right of the containing box:
       #
@@ -336,7 +371,7 @@ module Prawn
       #  end
       #
       def top_left
-        [left,top]
+        [left, top]
       end
 
       # Relative top-right point of the bounding box
@@ -349,7 +384,7 @@ module Prawn
       #  end
       #
       def top_right
-        [right,top]
+        [right, top]
       end
 
       # Relative bottom-right point of the bounding box
@@ -361,7 +396,7 @@ module Prawn
       #  end
       #
       def bottom_right
-        [right,bottom]
+        [right, bottom]
       end
 
       # Relative bottom-left point of the bounding box
@@ -373,7 +408,7 @@ module Prawn
       #  end
       #
       def bottom_left
-        [left,bottom]
+        [left, bottom]
       end
 
       # Absolute left x-coordinate of the bounding box
@@ -425,10 +460,7 @@ module Prawn
       end
 
       # Width of the bounding box
-      #
-      def width
-        @width
-      end
+      attr_reader :width
 
       # Height of the bounding box.  If the box is 'stretchy' (unspecified
       # height attribute), height is calculated as the distance from the top of
@@ -436,20 +468,27 @@ module Prawn
       #
       def height
         return @height if @height
-        @stretched_height = [(absolute_top - @document.y),
-                             @stretched_height.to_f].max
+
+        @stretched_height = [
+          (absolute_top - @document.y),
+          @stretched_height.to_f
+        ].max
       end
 
       # an alias for absolute_left
+      # @private
       def left_side
         absolute_left
       end
 
       # an alias for absolute_right
+      # @private
       def right_side
         absolute_right
       end
 
+      # @group Extension API
+
       # Moves to the top of the next page of the document, starting a new page
       # if necessary.
       #
@@ -461,11 +500,9 @@ module Prawn
         end
       end
 
-
-      alias_method :update_height, :height
-
-      # Returns +false+ when the box has a defined height, +true+ when the height
-      # is being calculated on the fly based on the current vertical position.
+      # Returns +false+ when the box has a defined height, +true+ when the
+      # height is being calculated on the fly based on the current vertical
+      # position.
       #
       def stretchy?
         !@height
@@ -475,23 +512,30 @@ module Prawn
       #
       def reference_bounds
         if stretchy?
-          raise "Can't find reference bounds: my parent is unset" unless @parent
+          raise NoReferenceBounds unless @parent
+
           @parent.reference_bounds
         else
           self
         end
       end
 
+      alias update_height height
+
       # Returns a deep copy of these bounds (including all parent bounds but
       # not copying the reference to the Document).
       #
+      # @private
       def deep_copy
         copy = dup
         # Deep-copy the parent bounds
-        copy.instance_variable_set("@parent", if BoundingBox === @parent
-                                                @parent.deep_copy
-                                              end)
-        copy.instance_variable_set("@document", nil)
+        copy.instance_variable_set(
+          '@parent',
+          if @parent.is_a?(BoundingBox)
+            @parent.deep_copy
+          end
+        )
+        copy.instance_variable_set('@document', nil)
         copy
       end
 
@@ -499,12 +543,11 @@ module Prawn
       # context of the given +document+. Does *not* set the bounds of the
       # document to the resulting BoundingBox, only returns it.
       #
+      # @private
       def self.restore_deep_copy(bounds, document)
-        bounds.instance_variable_set("@document", document)
+        bounds.instance_variable_set('@document', document)
         bounds
       end
-
     end
-
   end
 end

data/lib/prawn/document/column_box.rb

@@ -1,12 +1,16 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # column_box.rb: Extends BoundingBox to allow for columns of text
 #
 # Author Paul Ostazeski.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+require_relative 'bounding_box'
 
-require "prawn/document/bounding_box"
 module Prawn
   class Document
+    # @group Experimental API
 
     # A column box is a bounding box with the additional property that when
     # text flows past the bottom, it will wrap first to another column on the
@@ -14,9 +18,12 @@ module Prawn
     # filled.
     #
     # column_box accepts the same parameters as bounding_box, as well as the
-    # number of :columns and a :spacer (in points) between columns.
+    # number of :columns and a :spacer (in points) between columns. If resetting
+    # the top margin is desired on a new page (e.g. to allow for initial page
+    # wide column titles) the option :reflow_margins => true can be set.
     #
-    # Defaults are :columns = 3 and :spacer = font_size
+    # Defaults are :columns = 3, :spacer = font_size, and
+    # :reflow_margins => false
     #
     # Under PDF::Writer, "spacer" was known as "gutter"
     #
@@ -29,10 +36,10 @@ module Prawn
 
     private
 
-    def init_column_box(user_block, options={}, &init_block)
+    def init_column_box(user_block, options = {})
       parent_box = @bounding_box
 
-      init_block.call(parent_box)
+      yield(parent_box)
 
       self.y = @bounding_box.absolute_top
       user_block.call
@@ -45,12 +52,12 @@ module Prawn
     # work.
     #
     class ColumnBox < BoundingBox
-
-      def initialize(document, parent, point, options={}) #:nodoc:
+      def initialize(document, parent, point, options = {}) #:nodoc:
         super
         @columns = options[:columns] || 3
-        @spacer  = options[:spacer]  || @document.font_size
+        @spacer = options[:spacer] || @document.font_size
         @current_column = 0
+        @reflow_margins = options[:reflow_margins]
       end
 
       # The column width, not the width of the whole box,
@@ -102,7 +109,10 @@ module Prawn
       def move_past_bottom
         @current_column = (@current_column + 1) % @columns
         @document.y = @y
-        if 0 == @current_column
+        if @current_column.zero?
+          if @reflow_margins
+            @y = @parent.absolute_top
+          end
           @document.start_new_page
         end
       end