prawn 2.1.0 → 2.2.0

data/lib/prawn/measurement_extensions.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 # measurement_extensions.rb: Core extensions for Prawn::Measurements
 #
 # Copyright December 2008, Florian Witteler.  All Rights Reserved.
@@ -17,34 +16,34 @@ class Numeric
   # @group Experimental API
 
   def mm
-    return mm2pt(self)
+    mm2pt(self)
   end
 
   def cm
-    return cm2pt(self)
+    cm2pt(self)
   end
 
   def dm
-    return dm2pt(self)
+    dm2pt(self)
   end
 
   def m
-    return m2pt(self)
+    m2pt(self)
   end
 
   def in
-    return in2pt(self)
+    in2pt(self)
   end
 
   def yd
-    return yd2pt(self)
+    yd2pt(self)
   end
 
   def ft
-    return ft2pt(self)
+    ft2pt(self)
   end
 
   def pt
-    return pt2pt(self)
+    pt2pt(self)
   end
 end

data/lib/prawn/measurements.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 # measurements.rb: Conversions from other measurements to PDF points
 #
 # Copyright December 2008, Florian Witteler.  All Rights Reserved.
@@ -9,62 +8,62 @@ module Prawn
   module Measurements
     # metric conversions
     def cm2mm(cm)
-      return cm * 10
+      cm * 10
     end
 
     def dm2mm(dm)
-      return dm * 100
+      dm * 100
     end
 
     def m2mm(m)
-      return m * 1000
+      m * 1000
     end
 
     # imperial conversions
     # from http://en.wikipedia.org/wiki/Imperial_units
     def ft2in(ft)
-      return ft * 12
+      ft * 12
     end
 
     def yd2in(yd)
-      return yd * 36
+      yd * 36
     end
 
     # PostscriptPoint-converisons
     def pt2pt(pt)
-      return pt
+      pt
     end
 
     def in2pt(inch)
-      return inch * 72
+      inch * 72
     end
 
     def ft2pt(ft)
-      return in2pt(ft2in(ft))
+      in2pt(ft2in(ft))
     end
 
     def yd2pt(yd)
-      return in2pt(yd2in(yd))
+      in2pt(yd2in(yd))
     end
 
     def mm2pt(mm)
-      return mm * (72 / 25.4)
+      mm * (72 / 25.4)
     end
 
     def cm2pt(cm)
-      return mm2pt(cm2mm(cm))
+      mm2pt(cm2mm(cm))
     end
 
     def dm2pt(dm)
-      return mm2pt(dm2mm(dm))
+      mm2pt(dm2mm(dm))
     end
 
     def m2pt(m)
-      return mm2pt(m2mm(m))
+      mm2pt(m2mm(m))
     end
 
     def pt2mm(pt)
-      return pt * 1 / mm2pt(1) # (25.4 / 72)
+      pt * 1 / mm2pt(1) # (25.4 / 72)
     end
   end
 end

data/lib/prawn/outline.rb

@@ -1,26 +1,26 @@
-# encoding: utf-8
-
 module Prawn
   class Document
     # @group Stable API
 
-    # Lazily instantiates a Prawn::Outline object for document. This is used as point of entry
-    # to methods to build the outline tree for a document's table of contents.
+    # Lazily instantiates a Prawn::Outline object for document. This is used as
+    # point of entry to methods to build the outline tree for a document's table
+    # of contents.
     def outline
       @outline ||= Outline.new(self)
     end
   end
 
   # The Outline class organizes the outline tree items for the document.
-  # Note that the prev and parent instance variables are adjusted while navigating
-  # through the nested blocks. These variables along with the presence or absense
-  # of blocks are the primary means by which the relations for the various
-  # OutlineItems and the OutlineRoot are set. Unfortunately, the best way to
-  # understand how this works is to follow the method calls through a real example.
+  # Note that the prev and parent instance variables are adjusted while
+  # navigating through the nested blocks. These variables along with the
+  # presence or absense of blocks are the primary means by which the relations
+  # for the various OutlineItems and the OutlineRoot are set. Unfortunately, the
+  # best way to understand how this works is to follow the method calls through
+  # a real example.
   #
-  # Some ideas for the organization of this class were gleaned from name_tree. In
-  # particular the way in which the OutlineItems are finally rendered into document
-  # objects in PdfObject through a hash.
+  # Some ideas for the organization of this class were gleaned from name_tree.
+  # In particular the way in which the OutlineItems are finally rendered into
+  # document objects in PdfObject through a hash.
   #
   class Outline
     # @private
@@ -42,10 +42,11 @@ module Prawn
 
     # Defines/Updates an outline for the document.
     # The outline is an optional nested index that appears on the side of a PDF
-    # document usually with direct links to pages. The outline DSL is defined by nested
-    # blocks involving two methods: section and page; see the documentation on those methods
-    # for their arguments and options. Note that one can also use outline#update
-    # to add more sections to the end of the outline tree using the same syntax and scope.
+    # document usually with direct links to pages. The outline DSL is defined by
+    # nested blocks involving two methods: section and page; see the
+    # documentation on those methods for their arguments and options. Note that
+    # one can also use outline#update to add more sections to the end of the
+    # outline tree using the same syntax and scope.
     #
     # The syntax is best illustrated with an example:
     #
@@ -69,28 +70,31 @@ module Prawn
     # end
     #
     def define(&block)
-      instance_eval(&block)  if block
+      instance_eval(&block) if block
     end
 
-    alias :update :define
+    alias update define
 
     # Inserts an outline section to the outline tree (see outline#define).
     # Although you will probably choose to exclusively use outline#define so
-    # that your outline tree is contained and easy to manage, this method
-    # gives you the option to insert sections to the outline tree at any point
-    # during document generation. This method allows you to add a child subsection
-    # to any other item at any level in the outline tree.
-    # Currently the only way to locate the place of entry is with the title for the
-    # item. If your title names are not unique consider using define_outline.
+    # that your outline tree is contained and easy to manage, this method gives
+    # you the option to insert sections to the outline tree at any point during
+    # document generation. This method allows you to add a child subsection to
+    # any other item at any level in the outline tree.  Currently the only way
+    # to locate the place of entry is with the title for the item. If your title
+    # names are not unique consider using define_outline.
     # The method takes the following arguments:
-    #   title: a string that must match an outline title to add the subsection to
-    #   position: either :first or :last(the default) where the subsection will be placed relative
-    #      to other child elements. If you need to position your subsection in between
-    #      other elements then consider using #insert_section_after
+    #   title: a string that must match an outline title to add
+    #     the subsection to
+    #   position: either :first or :last (the default) where the subsection will
+    #     be placed relative to other child elements. If you need to position
+    #     your subsection in between other elements then consider using
+    #     #insert_section_after
     #   block: uses the same DSL syntax as outline#define, for example:
     #
-    # Consider using this method inside of outline.update if you want to have the outline object
-    # to be scoped as self (see #insert_section_after example).
+    # Consider using this method inside of outline.update if you want to have
+    # the outline object to be scoped as self (see #insert_section_after
+    # example).
     #
     #   go_to_page 2
     #   start_new_page
@@ -101,8 +105,10 @@ module Prawn
     #
     def add_subsection_to(title, position = :last, &block)
       @parent = items[title]
-      fail Prawn::Errors::UnknownOutlineTitle,
-           "\n No outline item with title: '#{title}' exists in the outline tree" unless @parent
+      unless @parent
+        raise Prawn::Errors::UnknownOutlineTitle,
+          "\n No outline item with title: '#{title}' exists in the outline tree"
+      end
       @prev = position == :first ? nil : @parent.data.last
       nxt = position == :first ? @parent.data.first : nil
       insert_section(nxt, &block)
@@ -110,12 +116,13 @@ module Prawn
 
     # Inserts an outline section to the outline tree (see outline#define).
     # Although you will probably choose to exclusively use outline#define so
-    # that your outline tree is contained and easy to manage, this method
-    # gives you the option to insert sections to the outline tree at any point
-    # during document generation. Unlike outline.add_section, this method allows
-    # you to enter a section after any other item at any level in the outline tree.
-    # Currently the only way to locate the place of entry is with the title for the
-    # item. If your title names are not unique consider using define_outline.
+    # that your outline tree is contained and easy to manage, this method gives
+    # you the option to insert sections to the outline tree at any point during
+    # document generation. Unlike outline.add_section, this method allows you to
+    # enter a section after any other item at any level in the outline tree.
+    # Currently the only way to locate the place of entry is with the title for
+    # the item. If your title names are not unique consider using
+    # define_outline.
     # The method takes the following arguments:
     #   title: the title of other section or page to insert new section after
     #   block: uses the same DSL syntax as outline#define, for example:
@@ -131,30 +138,36 @@ module Prawn
     #
     def insert_section_after(title, &block)
       @prev = items[title]
-      fail Prawn::Errors::UnknownOutlineTitle,
-           "\n No outline item with title: '#{title}' exists in the outline tree" unless @prev
+      unless @prev
+        raise Prawn::Errors::UnknownOutlineTitle,
+          "\n No outline item with title: '#{title}' exists in the outline tree"
+      end
       @parent = @prev.data.parent
       nxt = @prev.data.next
       insert_section(nxt, &block)
     end
 
-    # See outline#define above for documentation on how this is used in that context
+    # See outline#define above for documentation on how this is used in that
+    # context
     #
     # Adds an outine section to the outline tree.
     # Although you will probably choose to exclusively use outline#define so
-    # that your outline tree is contained and easy to manage, this method
-    # gives you the option to add sections to the outline tree at any point
-    # during document generation. When not being called from within another #section block
-    # the section will be added at the top level after the other root elements of the outline.
-    # For more flexible placement try using outline#insert_section_after and/or
-    # outline#add_subsection_to
+    # that your outline tree is contained and easy to manage, this method gives
+    # you the option to add sections to the outline tree at any point during
+    # document generation. When not being called from within another #section
+    # block the section will be added at the top level after the other root
+    # elements of the outline.  For more flexible placement try using
+    # outline#insert_section_after and/or outline#add_subsection_to
+    #
     # Takes the following arguments:
     #   title: the outline text that appears for the section.
-    #   options: destination - optional integer defining the page number for a destination link
-    #                          to the top of the page (using a :FIT destination).
-    #                 - or an array with a custom destination (see the #dest_* methods of the
-    #                   PDF::Destination module)
-    #            closed - whether the section should show its nested outline elements.
+    #   options: destination - optional integer defining the page number for
+    #                 a destination link to the top of the page (using a :FIT
+    #                 destination).
+    #                 - or an array with a custom destination (see the #dest_*
+    #                 methods of the PDF::Destination module)
+    #            closed - whether the section should show its nested outline
+    #                     elements.
     #                   - defaults to false.
     #            block: more nested subsections and/or page blocks
     #
@@ -167,36 +180,40 @@ module Prawn
       add_outline_item(title, options, &block)
     end
 
-    # See Outline#define above for more documentation on how it is used in that context
+    # See Outline#define above for more documentation on how it is used in that
+    # context
     #
     # Adds a page to the outline.
     # Although you will probably choose to exclusively use outline#define so
     # that your outline tree is contained and easy to manage, this method also
     # gives you the option to add pages to the root of outline tree at any point
-    # during document generation. Note that the page will be added at the
-    # top level after the other root outline elements. For more flexible placement try
-    # using outline#insert_section_after and/or outline#add_subsection_to.
+    # during document generation. Note that the page will be added at the top
+    # level after the other root outline elements. For more flexible placement
+    # try using outline#insert_section_after and/or outline#add_subsection_to.
     #
     # Takes the following arguments:
-    #     options:
-    #            title - REQUIRED. The outline text that appears for the page.
-    #            destination - optional integer defining the page number for a destination link
-    #                          to the top of the page (using a :FIT destination).
-    #                 - or an array with a custom destination (see the #dest_* methods of the
-    #                   PDF::Destination module)
-    #            closed - whether the section should show its nested outline elements.
-    #                   - defaults to false.
+    #   options:
+    #     title - REQUIRED. The outline text that appears for the page.
+    #     destination - optional integer defining the page number for
+    #             a destination link to the top of the page (using a :FIT
+    #             destination).
+    #             or an array with a custom destination (see the dest_* methods
+    #             of the PDF::Destination module)
+    #     closed - whether the section should show its nested outline elements.
+    #            - defaults to false.
     # example usage:
     #
     #   outline.page :title => "Very Last Page"
-    # Note: this method is almost identical to section except that it does not accept a block
-    # thereby defining the outline item as a leaf on the outline tree structure.
+    #
+    # Note: this method is almost identical to section except that it does not
+    # accept a block thereby defining the outline item as a leaf on the outline
+    # tree structure.
     def page(options = {})
       if options[:title]
         title = options[:title]
       else
-        fail Prawn::Errors::RequiredOption,
-             "\nTitle is a required option for page"
+        raise Prawn::Errors::RequiredOption,
+          "\nTitle is a required option for page"
       end
       add_outline_item(title, options)
     end
@@ -207,15 +224,16 @@ module Prawn
     # lazily initialized, so that documents that do not have an outline
     # do not incur the additional overhead.
     def root
-      document.state.store.root.data[:Outlines] ||= document.ref!(PDF::Core::OutlineRoot.new)
+      document.state.store.root.data[:Outlines] ||=
+        document.ref!(PDF::Core::OutlineRoot.new)
     end
 
     def add_outline_item(title, options, &block)
       outline_item = create_outline_item(title, options)
-      set_relations(outline_item)
+      establish_relations(outline_item)
       increase_count
       set_variables_for_block(outline_item, block)
-      block.call if block
+      yield if block
       reset_parent(outline_item)
     end
 
@@ -234,7 +252,7 @@ module Prawn
       items[title] = document.ref!(outline_item)
     end
 
-    def set_relations(outline_item)
+    def establish_relations(outline_item)
       prev.data.next = outline_item if prev
       parent.data.first = outline_item unless prev
       parent.data.last = outline_item
@@ -244,11 +262,11 @@ module Prawn
       counting_parent = parent
       while counting_parent
         counting_parent.data.count += 1
-        if counting_parent == root
-          counting_parent = nil
-        else
-          counting_parent = counting_parent.data.parent
-        end
+        counting_parent = if counting_parent == root
+                            nil
+                          else
+                            counting_parent.data.parent
+                          end
       end
     end
 
@@ -267,7 +285,7 @@ module Prawn
     def insert_section(nxt, &block)
       last = @parent.data.last
       if block
-        block.call
+        yield
       end
       adjust_relations(nxt, last)
       reset_root_positioning

data/lib/prawn/repeater.rb

@@ -1,5 +1,3 @@
-# encoding: utf-8
-#
 # repeater.rb : Implements repeated page elements.
 # Heavy inspired by repeating_element() in PDF::Wrapper
 #   http://pdf-wrapper.rubyforge.org/
@@ -20,9 +18,9 @@ module Prawn
 
     # @group Experimental API
 
-    # Provides a way to execute a block of code repeatedly based on a
-    # page_filter.  Since Stamp is used under the hood, this method is very space
-    # efficient.
+    # Provides a way to execute a block of code repeatedly based on
+    # a page_filter.  Since Stamp is used under the hood, this method is very
+    # space efficient.
     #
     # Available page filters are:
     #   :all        -- repeats on every page
@@ -32,8 +30,9 @@ module Prawn
     #   some_range  -- repeats on every page included in the range
     #   some_lambda -- yields page number and repeats for true return values
     #
-    # Also accepts an optional second argument for dynamic content which executes the code
-    # in the context of the filtered pages without using a Stamp.
+    # Also accepts an optional second argument for dynamic content which
+    # executes the code in the context of the filtered pages without using
+    # a Stamp.
     #
     # Example:
     #
@@ -75,7 +74,10 @@ module Prawn
     #   end
     #
     def repeat(page_filter, options = {}, &block)
-      repeaters << Prawn::Repeater.new(self, page_filter, !!options[:dynamic], &block)
+      dynamic = options.fetch(:dynamic, false)
+      repeaters << Prawn::Repeater.new(
+        self, page_filter, dynamic, &block
+      )
     end
   end
 
@@ -91,10 +93,10 @@ module Prawn
     attr_reader :name
 
     def initialize(document, page_filter, dynamic = false, &block)
-      @document    = document
+      @document = document
       @page_filter = page_filter
       @dynamic = dynamic
-      @stamp_name  = "prawn_repeater(#{Repeater.count})"
+      @stamp_name = "prawn_repeater(#{Repeater.count})"
       @document.create_stamp(@stamp_name, &block) unless dynamic
       @block = block if dynamic
       @graphic_state = document.state.page.graphic_state.dup