prawn 0.13.0 → 2.4.0

data/lib/prawn/measurement_extensions.rb

@@ -1,46 +1,51 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 # measurement_extensions.rb: Core extensions for Prawn::Measurements
 #
 # Copyright December 2008, Florian Witteler.  All Rights Reserved.
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
 
-require 'prawn/measurements'
+require_relative 'measurements'
+
+# @group Stable API
 
 class Numeric
   include Prawn::Measurements
   # prawns' basic unit is PostScript-Point
   # 72 points per inch
 
+  # @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,75 +1,74 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 # measurements.rb: Conversions from other measurements to PDF points
 #
 # Copyright December 2008, Florian Witteler.  All Rights Reserved.
 #
+
+# rubocop: disable Naming/MethodParameterName
 module Prawn
-  module Measurements
+  # @group Stable API
 
-    # ============================================================================
-    #metric conversions
+  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
+# rubocop: enable Naming/MethodParameterName

data/lib/prawn/outline.rb

@@ -1,22 +1,310 @@
-# encoding: utf-8
-#
-# generates outline dictionary and items for document
-#
-# Author Jonathan Greenberg
-
-require 'forwardable'
-require_relative "../pdf/core/outline"
+# frozen_string_literal: true
 
 module Prawn
-
   class Document
+    # @group Stable API
 
-    # Lazily instantiates an Outline object for document. This is used as point of entry
-    # to methods to build the outline tree.
+    # 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 ||= PDF::Core::Outline.new(self)
+      @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.
+  #
+  # 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
+    attr_accessor :parent, :prev, :document, :items
+
+    def initialize(document)
+      @document = document
+      @parent = root
+      @prev = nil
+      @items = {}
+    end
+
+    # @group Stable API
+
+    # Returns the current page number of the document
+    def page_number
+      @document.page_number
+    end
+
+    # 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.
+    #
+    # The syntax is best illustrated with an example:
+    #
+    # Prawn::Document.generate(outlined_document.pdf) do
+    #   text "Page 1. This is the first Chapter. "
+    #   start_new_page
+    #   text "Page 2. More in the first Chapter. "
+    #   start_new_page
+    #   outline.define do
+    #     section 'Chapter 1', :destination => 1, :closed => true do
+    #       page :destination => 1, :title => 'Page 1'
+    #       page :destination => 2, :title => 'Page 2'
+    #     end
+    #   end
+    #   start_new_page do
+    #   outline.update do
+    #     section 'Chapter 2', :destination =>  2, do
+    #       page :destination => 3, :title => 'Page 3'
+    #     end
+    #   end
+    # end
+    #
+    def define(&block)
+      instance_eval(&block) if block
+    end
+
+    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.
+    # 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
+    #   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).
+    #
+    #   go_to_page 2
+    #   start_new_page
+    #   text "Inserted Page"
+    #   outline.add_subsection_to :title => 'Page 2', :first do
+    #     outline.page :destination => page_number, :title => "Inserted Page"
+    #   end
+    #
+    def add_subsection_to(title, position = :last, &block)
+      @parent = items[title]
+      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)
+    end
+
+    # 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.
+    # 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:
+    #
+    #   go_to_page 2
+    #   start_new_page
+    #   text "Inserted Page"
+    #   update_outline do
+    #     insert_section_after :title => 'Page 2' do
+    #       page :destination => page_number, :title => "Inserted Page"
+    #     end
+    #   end
+    #
+    def insert_section_after(title, &block)
+      @prev = items[title]
+      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
+    #
+    # 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
+    #
+    # 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.
+    #                   - defaults to false.
+    #            block: more nested subsections and/or page blocks
+    #
+    # example usage:
+    #
+    #   outline.section 'Added Section', :destination => 3 do
+    #     outline.page :destionation => 3, :title => 'Page 3'
+    #   end
+    def section(title, options = {}, &block)
+      add_outline_item(title, options, &block)
+    end
+
+    # 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.
+    #
+    # 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.
+    # 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.
+    def page(options = {})
+      if options[:title]
+        title = options[:title]
+      else
+        raise Prawn::Errors::RequiredOption,
+          "\nTitle is a required option for page"
+      end
+      add_outline_item(title, options)
+    end
+
+    private
+
+    # The Outline dictionary (12.3.3) for this document.  It is
+    # 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)
+    end
+
+    def add_outline_item(title, options, &block)
+      outline_item = create_outline_item(title, options)
+      establish_relations(outline_item)
+      increase_count
+      set_variables_for_block(outline_item, block)
+      yield if block
+      reset_parent(outline_item)
+    end
+
+    def create_outline_item(title, options)
+      outline_item = PDF::Core::OutlineItem.new(title, parent, options)
+
+      case options[:destination]
+      when Integer
+        page_index = options[:destination] - 1
+        outline_item.dest = [document.state.pages[page_index].dictionary, :Fit]
+      when Array
+        outline_item.dest = options[:destination]
+      end
+
+      outline_item.prev = prev if @prev
+      items[title] = document.ref!(outline_item)
+    end
+
+    def establish_relations(outline_item)
+      prev.data.next = outline_item if prev
+      parent.data.first = outline_item unless prev
+      parent.data.last = outline_item
+    end
+
+    def increase_count
+      counting_parent = parent
+      while counting_parent
+        counting_parent.data.count += 1
+        counting_parent =
+          if counting_parent == root
+            nil
+          else
+            counting_parent.data.parent
+          end
+      end
+    end
+
+    def set_variables_for_block(outline_item, block)
+      self.prev = block ? nil : outline_item
+      self.parent = outline_item if block
+    end
+
+    def reset_parent(outline_item)
+      if parent == outline_item
+        self.prev = outline_item
+        self.parent = outline_item.data.parent
+      end
+    end
+
+    def insert_section(nxt, &block)
+      last = @parent.data.last
+      if block
+        yield
+      end
+      adjust_relations(nxt, last)
+      reset_root_positioning
+    end
+
+    def adjust_relations(nxt, last)
+      if nxt
+        nxt.data.prev = @prev
+        @prev.data.next = nxt
+        @parent.data.last = last
+      end
+    end
+
+    def reset_root_positioning
+      @parent = root
+      @prev = root.data.last
+    end
+  end
 end

data/lib/prawn/repeater.rb

@@ -1,5 +1,5 @@
-# encoding: utf-8
-#
+# frozen_string_literal: true
+
 # repeater.rb : Implements repeated page elements.
 # Heavy inspired by repeating_element() in PDF::Wrapper
 #   http://pdf-wrapper.rubyforge.org/
@@ -9,19 +9,20 @@
 # This is free software. Please see the LICENSE and COPYING files for details.
 
 module Prawn
-
   class Document
-
     # A list of all repeaters in the document.
     # See Document#repeat for details
     #
+    # @private
     def repeaters
       @repeaters ||= []
     end
 
-    # 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.
+    # @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.
     #
     # Available page filters are:
     #   :all        -- repeats on every page
@@ -31,8 +32,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:
     #
@@ -73,8 +75,11 @@ module Prawn
     #
     #   end
     #
-    def repeat(page_filter, options={}, &block)
-      repeaters << Prawn::Repeater.new(self, page_filter, !!options[:dynamic], &block)
+    def repeat(page_filter, options = {}, &block)
+      dynamic = options.fetch(:dynamic, false)
+      repeaters << Prawn::Repeater.new(
+        self, page_filter, dynamic, &block
+      )
     end
   end
 
@@ -90,10 +95,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
@@ -110,13 +115,10 @@ module Prawn
         @document.stamp(@stamp_name) if match?(page_number)
       elsif @block && match?(page_number)
         @document.save_graphics_state(@graphic_state) do
-          @document.send(:freeze_stamp_graphics)
+          @document.__send__(:freeze_stamp_graphics)
           @block.call
         end
       end
     end
-
   end
 end
-
-

data/lib/prawn/security/arcfour.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Implementation of the "ARCFOUR" algorithm ("alleged RC4 (tm)"). Implemented
+# as described at:
+# http://www.mozilla.org/projects/security/pki/nss/draft-kaukonen-cipher-arcfour-03.txt
+#
+# "RC4" is a trademark of RSA Data Security, Inc.
+#
+# Copyright August 2009, Brad Ediger. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+# @private
+class Arcfour
+  def initialize(key)
+    # Convert string key to Array of integers
+    key = key.unpack('c*') if key.is_a?(String)
+
+    # 1. Allocate an 256 element array of 8 bit bytes to be used as an S-box
+    # 2. Initialize the S-box.  Fill each entry first with it's index
+    @sbox = (0..255).to_a
+
+    # 3. Fill another array of the same size (256) with the key, repeating
+    #    bytes as necessary.
+    s2 = []
+    while s2.length < 256
+      s2 += key
+    end
+    s2 = s2[0, 256]
+
+    # 4. Set j to zero and initialize the S-box
+    j = 0
+    (0..255).each do |i|
+      j = (j + @sbox[i] + s2[i]) % 256
+      @sbox[i], @sbox[j] = @sbox[j], @sbox[i]
+    end
+
+    @i = @j = 0
+  end
+
+  def encrypt(string)
+    string.unpack('c*').map { |byte| byte ^ key_byte }.pack('c*')
+  end
+
+  private
+
+  # Produces the next byte of key material in the stream (3.2 Stream Generation)
+  def key_byte
+    @i = (@i + 1) % 256
+    @j = (@j + @sbox[@i]) % 256
+    @sbox[@i], @sbox[@j] = @sbox[@j], @sbox[@i]
+    @sbox[(@sbox[@i] + @sbox[@j]) % 256]
+  end
+end