piglop-prawn 0.10.2.1

data/lib/prawn/security.rb

@@ -0,0 +1,262 @@
+# encoding: utf-8
+#
+# encryption.rb : Implements encrypted PDF and access permissions.
+#
+# Copyright August 2008, Brad Ediger. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+require 'digest/md5'
+require 'prawn/security/arcfour'
+require 'prawn/core/byte_string'
+
+module Prawn
+  class Document
+    
+    # Implements PDF encryption (password protection and permissions) as
+    # specified in the PDF Reference, version 1.3, section 3.5 "Encryption".
+    module Security
+      include Prawn::Core
+      
+      # Encrypts the document, to protect confidential data or control
+      # modifications to the document. The encryption algorithm used is
+      # detailed in the PDF Reference 1.3, section 3.5 "Encryption", and it is
+      # implemented by all major PDF readers.
+      #
+      # +options+ can contain the following:
+      # 
+      # <tt>:user_password</tt>:: Password required to open the document. If 
+      #                           this is omitted or empty, no password will be
+      #                           required. The document will still be
+      #                           encrypted, but anyone can read it.
+      #
+      # <tt>:owner_password</tt>:: Password required to make modifications to 
+      #                            the document or change or override its
+      #                            permissions. If this is set to
+      #                            <tt>:random</tt>, a random password will be
+      #                            used; this can be useful if you never want
+      #                            users to be able to override the document
+      #                            permissions.
+      #
+      # <tt>:permissions</tt>:: A hash mapping permission symbols (see below) to
+      #                         <tt>true</tt> or <tt>false</tt>. True means
+      #                         "permitted", and false means "not permitted".
+      #                         All permissions default to <tt>true</tt>.
+      #
+      # The following permissions can be specified:
+      #
+      # <tt>:print_document</tt>:: Print document.
+      #
+      # <tt>:modify_document</tt>:: Modify contents of document (other than text
+      #                             annotations and interactive form fields).
+      #
+      # <tt>:copy_contents</tt>:: Copy text and graphics from document.
+      #
+      # <tt>:modify_annotations</tt>:: Add or modify text annotations and 
+      #                                interactive form fields.
+      #
+      # == Examples
+      #
+      # Deny printing to everyone, but allow anyone to open without a password:
+      #
+      #   encrypt_document :permissions => { :print_document => false },
+      #                    :owner_password => :random
+      #
+      # Set a user and owner password on the document, with full permissions for
+      # both the user and the owner:
+      #
+      #   encrypt_document :user_password => 'foo', :owner_password => 'bar'
+      # 
+      # Set no passwords, grant all permissions (This is useful because the 
+      # default in some readers, if no permissions are specified, is "deny"):
+      #
+      #   encrypt_document
+      #
+      # == Caveats
+      #
+      # * The encryption used is weak; the key is password-derived and is
+      #   limited to 40 bits, due to US export controls in effect at the time
+      #   the PDF standard was written.
+      # 
+      # * There is nothing technologically requiring PDF readers to respect the
+      #   permissions embedded in a document. Many PDF readers do not.
+      # 
+      # * In short, you have <b>no security at all</b> against a moderately
+      #   motivated person. Don't use this for anything super-serious. This is
+      #   not a limitation of Prawn, but is rather a built-in limitation of the
+      #   PDF format.
+      #
+      def encrypt_document(options={})
+        Prawn.verify_options [:user_password, :owner_password, :permissions],
+          options
+        @user_password = options.delete(:user_password) || ""
+
+        @owner_password = options.delete(:owner_password) || @user_password
+        if @owner_password == :random
+          # Generate a completely ridiculous password
+          @owner_password = (1..32).map{ rand(256) }.pack("c*")
+        end
+
+        self.permissions = options.delete(:permissions) || {}
+
+        # Shove the necessary entries in the trailer and enable encryption.
+        state.trailer[:Encrypt] = encryption_dictionary
+        state.encrypt = true
+        state.encryption_key = user_encryption_key
+      end
+      
+      # Encrypts the given string under the given key, also requiring the
+      # object ID and generation number of the reference.
+      # See Algorithm 3.1.
+      def self.encrypt_string(str, key, id, gen)
+        # Convert ID and Gen number into little-endian truncated byte strings
+        id = [id].pack('V')[0,3]
+        gen = [gen].pack('V')[0,2]
+        extended_key = "#{key}#{id}#{gen}"
+
+        # Compute the RC4 key from the extended key and perform the encryption
+        rc4_key = Digest::MD5.digest(extended_key)[0, 10]
+        Arcfour.new(rc4_key).encrypt(str)
+      end
+
+      private
+
+      # Provides the values for the trailer encryption dictionary.
+      def encryption_dictionary
+        { :Filter => :Standard, # default PDF security handler
+          :V      => 1,         # "Algorithm 3.1", PDF reference 1.3
+          :R      => 2,         # Revision 2 of the algorithm
+          :O      => ByteString.new(owner_password_hash),
+          :U      => ByteString.new(user_password_hash),
+          :P      => permissions_value }
+      end
+
+      # Flags in the permissions word, numbered as LSB = 1
+      PermissionsBits = { :print_document     => 3,
+                          :modify_contents    => 4,
+                          :copy_contents      => 5,
+                          :modify_annotations => 6 }
+      
+      FullPermissions = 0b1111_1111_1111_1111_1111_1111_1111_1111
+
+      def permissions=(perms={})
+        @permissions ||= FullPermissions
+        perms.each do |key, value|
+          # 0-based bit number, from LSB
+          bit_position = PermissionsBits[key] - 1
+
+          if value # set bit
+            @permissions |= (1 << bit_position)
+          else # clear bit
+            @permissions &= ~(1 << bit_position)
+          end
+        end
+      end
+
+      def permissions_value
+        @permissions || FullPermissions
+      end
+
+      PasswordPadding = 
+        "28BF4E5E4E758A4164004E56FFFA01082E2E00B6D0683E802F0CA9FE6453697A".
+        scan(/../).map{|x| x.to_i(16)}.pack("c*")
+      
+      # Pads or truncates a password to 32 bytes as per Alg 3.2.
+      def pad_password(password)
+        password = password[0, 32]
+        password + PasswordPadding[0, 32 - password.length]
+      end
+
+      def user_encryption_key
+        @user_encryption_key ||= begin
+          md5 = Digest::MD5.new
+          md5 << pad_password(@user_password)
+          md5 << owner_password_hash
+          md5 << [permissions_value].pack("V")
+          md5.digest[0, 5]
+        end
+      end
+
+      # The O (owner) value in the encryption dictionary. Algorithm 3.3.
+      def owner_password_hash
+        @owner_password_hash ||= begin
+          key = Digest::MD5.digest(pad_password(@owner_password))[0, 5]
+          Arcfour.new(key).encrypt(pad_password(@user_password))
+        end
+      end
+
+      # The U (user) value in the encryption dictionary. Algorithm 3.4.
+      def user_password_hash
+        Arcfour.new(user_encryption_key).encrypt(PasswordPadding)
+      end
+
+    end
+
+  end
+
+  module Core #:nodoc:
+    module_function
+
+    # Like PdfObject, but returns an encrypted result if required.
+    # For direct objects, requires the object identifier and generation number
+    # from the indirect object referencing obj.
+    def EncryptedPdfObject(obj, key, id, gen, in_content_stream=false)
+      case obj
+      when Array
+        "[" << obj.map { |e|
+            EncryptedPdfObject(e, key, id, gen, in_content_stream)
+        }.join(' ') << "]"
+      when LiteralString
+        # FIXME: encrypted?
+        obj = obj.gsub(/[\\\n\(\)]/) { |m| "\\#{m}" }
+        "(#{obj})"
+      when Time
+        # FIXME: encrypted?
+        obj = obj.strftime("D:%Y%m%d%H%M%S%z").chop.chop + "'00'"
+        obj = obj.gsub(/[\\\n\(\)]/) { |m| "\\#{m}" }
+        "(#{obj})"
+      when String
+        PdfObject(
+          ByteString.new(
+            Document::Security.encrypt_string(obj, key, id, gen)),
+          in_content_stream)
+      when Hash
+        output = "<< "
+        obj.each do |k,v|
+          unless String === k || Symbol === k
+            raise Prawn::Errors::FailedObjectConversion,
+              "A PDF Dictionary must be keyed by names"
+          end
+          output << PdfObject(k.to_sym, in_content_stream) << " " <<
+                    EncryptedPdfObject(v, key, id, gen, in_content_stream) << "\n"
+        end
+        output << ">>"
+      when NameTree::Value
+        PdfObject(obj.name) + " " +
+          EncryptedPdfObject(obj.value, key, id, gen, in_content_stream)
+      else # delegate back to PdfObject
+        PdfObject(obj, in_content_stream)
+      end
+    end
+
+    class Reference
+
+      # Returns the object definition for the object this references, keyed from
+      # +key+.
+      def encrypted_object(key)
+        @on_encode.call(self) if @on_encode
+        output = "#{@identifier} #{gen} obj\n" <<
+          Prawn::Core::EncryptedPdfObject(data, key, @identifier, gen) << "\n"
+        if @stream
+          output << "stream\n" <<
+            Document::Security.encrypt_string(@stream, key, @identifier, gen) <<
+            "\nendstream\n"
+        end
+        output << "endobj\n"
+      end
+
+    end
+  end
+
+end
+

data/lib/prawn/stamp.rb

@@ -0,0 +1,126 @@
+# encoding: utf-8
+#
+# stamp.rb : Implements a repeatable stamp
+#
+# Copyright October 2009, Daniel Nelson. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+#
+
+module Prawn
+
+  # The Prawn::Stamp module is used to create content that will be
+  # included multiple times in a document. Using a stamp has three
+  # advantages over creating content anew each time it is placed on
+  # the page:
+  #   i.   faster document creation
+  #   ii.  smaller final document
+  #   iii. faster display on subsequent displays of the repeated
+  #   element because the viewer application can cache the rendered
+  #   results
+  #
+  # Example:
+  #   pdf.create_stamp("my_stamp") {
+  #     pdf.fill_circle_at([10, 15], :radius => 5)
+  #     pdf.draw_text("hello world", :at => [20, 10])
+  #   }
+  #   pdf.stamp("my_stamp")
+  #
+  module Stamp
+
+    # Renders the stamp named <tt>name</tt> to the page
+    # raises <tt>Prawn::Errors::InvalidName</tt> if name.empty?
+    # raises <tt>Prawn::Errors::UndefinedObjectName</tt> if no stamp
+    # has been created with this name
+    #
+    # Example:
+    #   pdf.create_stamp("my_stamp") {
+    #     pdf.fill_circle_at([10, 15], :radius => 5)
+    #     pdf.text("hello world", :at => [20, 10])
+    #   }
+    #   pdf.stamp("my_stamp")
+    #
+    def stamp(name)
+      dictionary_name, dictionary = stamp_dictionary(name)
+      add_content "/#{dictionary_name} Do"
+      state.page.xobjects.merge!(dictionary_name => dictionary)
+    end
+
+    # Renders the stamp named <tt>name</tt> at a position offset from
+    # the initial coords at which the elements of the stamp was
+    # created
+    #
+    # Example:
+    #   pdf.create_stamp("circle") do
+    #     pdf.fill_circle_at([0, 0], :radius => 25)
+    #   end
+    #   # draws a circle at 100, 100
+    #   pdf.stamp_at("circle", [100, 100])
+    #
+    # See stamp() for exceptions that might be raised
+    #
+    def stamp_at(name, point)
+      translate(point[0], point[1]) { stamp(name) }
+    end
+
+    # Creates a re-usable stamp named <tt>name</tt>
+    #
+    # raises <tt>Prawn::Errors::NameTaken</tt> if a stamp already
+    # exists in this document with this name
+    # raises <tt>Prawn::Errors::InvalidName</tt> if name.empty?
+    #
+    # Example:
+    #   pdf.create_stamp("my_stamp") {
+    #     pdf.fill_circle_at([10, 15], :radius => 5)
+    #     pdf.draw_text("hello world", :at => [20, 10])
+    #   }
+    #
+    def create_stamp(name, &block)
+      dictionary = create_stamp_dictionary(name)
+
+      state.page.stamp_stream(dictionary, &block)
+    end
+    
+    private
+
+    def stamp_dictionary_registry
+      @stamp_dictionary_registry ||= {}
+    end
+
+    def next_stamp_dictionary_id
+      stamp_dictionary_registry.length + 1
+    end
+
+    def stamp_dictionary(name)
+      raise Prawn::Errors::InvalidName if name.empty?
+      if stamp_dictionary_registry[name].nil?
+        raise Prawn::Errors::UndefinedObjectName
+      end
+
+      dict = stamp_dictionary_registry[name]
+
+      dictionary_name = dict[:stamp_dictionary_name]
+      dictionary = dict[:stamp_dictionary]
+      [dictionary_name, dictionary]
+    end
+
+    def create_stamp_dictionary(name)
+      raise Prawn::Errors::InvalidName if name.empty?
+      raise Prawn::Errors::NameTaken unless stamp_dictionary_registry[name].nil?
+      # BBox origin is the lower left margin of the page, so we need
+      # it to be the full dimension of the page, or else things that
+      # should appear near the top or right margin are invisible
+      dictionary = ref!(:Type    => :XObject,
+                        :Subtype => :Form,
+                        :BBox    => [0, 0,
+                                     state.page.dimensions[2], state.page.dimensions[3]])
+
+      dictionary_name = "Stamp#{next_stamp_dictionary_id}"
+
+      stamp_dictionary_registry[name] = { :stamp_dictionary_name => dictionary_name,
+                                          :stamp_dictionary      => dictionary }
+      dictionary
+    end
+
+  end
+end

data/lib/prawn/table/accessors.rb

@@ -0,0 +1,180 @@
+# encoding: utf-8
+
+# accessors.rb: Methods for accessing rows, columns, and cells of a
+# Prawn::Table.
+#
+# Copyright December 2009, Brad Ediger. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+module Prawn
+  
+  class Table
+
+    # Returns a CellProxy that can be used to select and style cells. See the
+    # CellProxy documentation for things you can do with cells.
+    #
+    def cells
+      @cell_proxy ||= CellProxy.new(@cells)
+    end
+
+    # Selects the given rows (0-based) for styling. Returns a CellProxy -- see
+    # the documentation on CellProxy for things you can do with cells.
+    #
+    def rows(row_spec)
+      cells.rows(row_spec)
+    end
+    alias_method :row, :rows
+
+    # Selects the given columns (0-based) for styling. Returns a CellProxy --
+    # see the documentation on CellProxy for things you can do with cells.
+    #
+    def columns(col_spec)
+      cells.columns(col_spec)
+    end
+    alias_method :column, :columns
+
+    # Represents a selection of cells to be styled. Operations on a CellProxy
+    # can be chained, and cell properties can be set one-for-all on the proxy.
+    #
+    # To set vertical borders only:
+    #
+    #   table.cells.borders = [:left, :right]
+    #
+    # To highlight a rectangular area of the table:
+    #
+    #   table.rows(1..3).columns(2..4).background_color = 'ff0000'
+    #
+    class CellProxy
+      def initialize(cells) #:nodoc:
+        @cells = cells
+      end
+
+      # Iterates over cells in turn.
+      #
+      def each(&b)
+        @cells.each(&b)
+      end
+
+      include Enumerable
+
+      # Limits selection to the given row or rows. +row_spec+ can be anything
+      # that responds to the === operator selecting a set of 0-based row
+      # numbers; most commonly a number or a range.
+      #
+      #   table.row(0)     # selects first row
+      #   table.rows(3..4) # selects rows four and five
+      #
+      def rows(row_spec)
+        CellProxy.new(@cells.select { |c| row_spec === c.row })
+      end
+      alias_method :row, :rows
+
+      # Limits selection to the given column or columns. +col_spec+ can be
+      # anything that responds to the === operator selecting a set of 0-based
+      # column numbers; most commonly a number or a range.
+      #
+      #   table.column(0)     # selects first column
+      #   table.columns(3..4) # selects columns four and five
+      #
+      def columns(col_spec)
+        CellProxy.new(@cells.select { |c| col_spec === c.column })
+      end
+      alias_method :column, :columns
+
+      # Selects cells based on a block.
+      #
+      #   table.column(4).select { |cell| cell.content =~ /Yes/ }.
+      #     background_color = 'ff0000'
+      #
+      def select(&b)
+        CellProxy.new(@cells.select(&b))
+      end
+
+      # Retrieves a cell based on its 0-based row and column. Returns a Cell,
+      # not a CellProxy.
+      # 
+      #   table.cells[0, 0].content # => "First cell content"
+      #
+      def [](row, col)
+        @cells.find { |c| c.row == row && c.column == col }
+      end
+
+      # Supports setting multiple properties at once.
+      #
+      #   table.cells.style(:padding => 0, :border_width => 2)
+      #
+      # is the same as:
+      #
+      #   table.cells.padding = 0
+      #   table.cells.border_width = 2
+      #
+      # You can also pass a block, which will be called for each cell in turn.
+      # This allows you to set more complicated properties:
+      #
+      #   table.cells.style { |cell| cell.border_width += 12 }
+      #
+      def style(options={}, &block)
+        @cells.each do |cell| 
+          options.each { |k, v| cell.send("#{k}=", v) }
+          block.call(cell) if block
+        end
+      end
+
+      # Returns the total width of all columns in the selected set.
+      #
+      def width
+        column_widths = {}
+        @cells.each do |cell| 
+          column_widths[cell.column] = 
+            [column_widths[cell.column], cell.width].compact.max
+        end
+        column_widths.values.inject(0) { |sum, width| sum + width }
+      end
+
+      # Returns minimum width required to contain cells in the set.
+      #
+      def min_width
+        column_min_widths = {}
+        @cells.each do |cell| 
+          column_min_widths[cell.column] = 
+            [column_min_widths[cell.column], cell.min_width].compact.max
+        end
+        column_min_widths.values.inject(0) { |sum, width| sum + width }
+      end
+
+      # Returns maximum width that can contain cells in the set.
+      #
+      def max_width
+        column_max_widths = {}
+        @cells.each do |cell| 
+          column_max_widths[cell.column] = 
+            [column_max_widths[cell.column], cell.max_width].compact.min
+        end
+        column_max_widths.values.inject(0) { |sum, width| sum + width }
+      end
+
+      # Returns the total height of all rows in the selected set.
+      #
+      def height
+        row_heights = {}
+        @cells.each do |cell| 
+          row_heights[cell.row] = 
+            [row_heights[cell.row], cell.height].compact.max
+        end
+        row_heights.values.inject(0) { |sum, width| sum + width }
+      end
+
+      # Supports setting arbitrary properties on a group of cells.
+      #
+      #   table.cells.row(3..6).background_color = 'cc0000'
+      #
+      def method_missing(id, *args, &block)
+        @cells.each { |c| c.send(id, *args, &block) }
+      end
+    end
+
+  end
+
+end
+
+

data/lib/prawn/table/cell/in_table.rb

@@ -0,0 +1,27 @@
+# encoding: utf-8
+
+# Accessors for using a Cell inside a Table.
+
+module Prawn
+  class Table    
+    class Cell
+
+      # This module extends Cell objects when they are used in a table (as
+      # opposed to standalone). Its properties apply to cells-in-tables but not
+      # cells themselves.
+      #
+      module InTable
+
+        # Row number (0-based).
+        #
+        attr_accessor :row
+        
+        # Column number (0-based).
+        #
+        attr_accessor :column
+
+      end
+
+    end
+  end
+end

data/lib/prawn/table/cell/subtable.rb

@@ -0,0 +1,65 @@
+# encoding: utf-8   
+
+# subtable.rb: Yo dawg.
+#
+# Copyright January 2010, Brad Ediger. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+module Prawn
+  class Table
+    class Cell
+
+      # A Cell that contains another table.
+      #
+      class Subtable < Cell
+
+        attr_reader :subtable
+
+        def initialize(pdf, point, options={})
+          super
+          @subtable = options[:content]
+
+          # Subtable padding defaults to zero
+          @padding = [0, 0, 0, 0]
+        end
+
+        # Sets the text color of the entire subtable.
+        #
+        def text_color=(color)
+          @subtable.cells.text_color = color
+        end
+
+        # Proxied to subtable.
+        #
+        def natural_content_width
+          @subtable.cells.width
+        end
+
+        # Proxied to subtable.
+        #
+        def min_width
+          @subtable.cells.min_width
+        end
+
+        # Proxied to subtable.
+        #
+        def max_width
+          @subtable.cells.max_width
+        end
+
+        # Proxied to subtable. 
+        #
+        def natural_content_height
+          @subtable.cells.height
+        end
+
+        # Draws the subtable.
+        #
+        def draw_content
+          @subtable.draw
+        end
+
+      end
+    end
+  end
+end