prawn 1.0.0.rc2 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: edf9e637f24e5c4554e995712cb589f0b21737fb
+  data.tar.gz: 97750f73864c853ff874f8a5a0f7984a6f9d8279
+SHA512:
+  metadata.gz: bd80b65ac0360fa6786b6bffacfc34a87511cc8d79e260dfd8db78b86a5003182a41d5ad559e5c1403724273c83b71b29d426c31a422fd7b1e5986a859ac1a5d
+  data.tar.gz: 4b63fc53c8481155ed173cb3e4b8146ac052173e0bd91f4fa27aece66525ad5f6968a48230addbb5ae2a043a3bc33829c79c9447a8c734f3bd2da45468b913da

data/.yardopts

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

data/COPYING

@@ -1,2 +1,2 @@
-Prawn may be used under Matz's terms for Ruby, or GPLv2 or GPLv3. See LICENSE
-for Matz's terms, or GPLv2 and GPLv3 files.
+Prawn may be used under Matz's original licensing terms for Ruby, or GPLv2 or GPLv3. 
+See LICENSE for Matz's terms, or GPLv2 and GPLv3 files.

data/Gemfile

@@ -1,18 +1,11 @@
-source :rubygems
+source "https://rubygems.org"
 
-gem "ttfunk", "~>1.0.3"
-gem "pdf-reader", "~> 1.2"
-gem "ruby-rc4"
-gem "afm"
+gemspec
 
-group :development do
-  gem "coderay", "~> 1.0.7"
-  gem "rdoc"
-end
-
-group :test do
-  gem "pdf-inspector", "~> 1.0.2", :require => "pdf/inspector"
-  gem "rspec"
-  gem "mocha", :require => false
-  gem "rake"
+if ENV["CI"] 
+  platforms :rbx do
+    gem "rubysl-singleton", "~> 2.0"
+    gem "rubysl-digest", "~> 2.0"
+    gem "rubysl-enumerator", "~> 2.0"
+  end
 end

data/LICENSE

@@ -1,7 +1,7 @@
 Prawn is copyrighted free software produced by Gregory Brown along with 
 community contributions.  See git log for authorship information.
 
-Licensing terms follow (License of Ruby):
+Licensing terms follow:
 
 You can redistribute Prawn and/or modify it under either the terms of the GPLv2
 or GPLv3 (see GPLv2 and GPLv3 files), or the conditions below:

data/Rakefile

@@ -3,32 +3,29 @@ Bundler.setup
 
 require 'rake'
 require 'rspec/core/rake_task'
-require 'rdoc/task'
+require 'yard'
 require 'rubygems/package_task'
 
 task :default => [:spec]
-       
+
 desc "Run all rspec files"
-RSpec::Core::RakeTask.new("spec")
+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
+  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",
-                           "COPYING",
-                           "LICENSE", 
-                           "HACKING", "lib/" )
-  rdoc.main     = "README"
-  rdoc.rdoc_dir = "doc/html"
-  rdoc.title    = "Prawn Documentation"
+YARD::Rake::YardocTask.new do |t|
+  t.options = ['--output-dir', 'doc/html']
 end
+task :docs => :yard
+
 
 desc "Generate the 'Prawn by Example' manual"
 task :manual do
@@ -43,3 +40,15 @@ Gem::PackageTask.new(spec) do |pkg|
   pkg.need_zip = true
   pkg.need_tar = true
 end
+
+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/data/images/license.md

@@ -0,0 +1,8 @@
+All images distributed with Prawn need to be freely distributable under
+a license that is compatible with our own (see LICENSE and COPYING files).
+
+It is our understanding that all files in this folder are compatible
+with our licensing, but if you notice any problems, please
+file an issue in our tracker on Github and we will promptly address it:
+
+https://github.com/prawnpdf/prawn/issues

data/lib/prawn.rb

@@ -1,29 +1,91 @@
 # 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.
-#
-module Prawn #:nodoc:
-  VERSION = "1.0.0.rc2"
+require "set"
+
+require 'ttfunk'
+require "pdf/core"
+
+module Prawn
+  VERSION = "1.0.0"
+
+  extend self
+
+  file = __FILE__
+  file = File.readlink(file) if File.symlink?(file)
+  dir  = File.dirname(file)
+
+  # The base source directory for Prawn as installed on the system
+  #
+  #
+  BASEDIR = File.expand_path(File.join(dir, '..'))
+  DATADIR = File.expand_path(File.join(dir, '..', 'data'))
+  
+  FLOAT_PRECISION = 1.0e-9
+
+  # Whe set to true, Prawn will verify hash options to ensure only valid keys
+  # are used.  Off by default.
+  #
+  # Example:
+  #   >> Prawn::Document.new(:tomato => "Juicy")
+  #   Prawn::Errors::UnknownOption:
+  #   Detected unknown option(s): [:tomato]
+  #   Accepted options are: [:page_size, :page_layout, :left_margin, ...]
+  #
+  attr_accessor :debug # @private
+
+  def verify_options(accepted, actual) # @private
+    return unless debug || $DEBUG
+    unless (act=Set[*actual.keys]).subset?(acc=Set[*accepted])
+      raise Prawn::Errors::UnknownOption,
+        "\nDetected unknown option(s): #{(act - acc).to_a.inspect}\n" <<
+        "Accepted options are: #{accepted.inspect}"
+    end
+    yield if block_given?
+  end
+
+  module Configurable # @private
+    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 "prawn/utilities"
-require "prawn/core"
-require "prawn/text"
-require "prawn/graphics"
-require "prawn/images"
-require "prawn/images/image"
-require "prawn/images/jpg"
-require "prawn/images/png"
-require "prawn/stamp"
-require "prawn/soft_mask"
-require "prawn/security"
-require "prawn/document"
-require "prawn/font"
-require "prawn/encoding"
-require "prawn/measurements"
-require "prawn/repeater"
-require "prawn/outline"
-require "prawn/layout"
+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/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"
+
+
 
+Prawn.image_handler.register(Prawn::Images::PNG)
+Prawn.image_handler.register(Prawn::Images::JPG)

data/lib/prawn/document.rb

@@ -7,13 +7,12 @@
 # This is free software. Please see the LICENSE and COPYING files for details.
 
 require "stringio"
-require "prawn/document/page_geometry"
-require "prawn/document/bounding_box"
-require "prawn/document/column_box"
-require "prawn/document/internals"
-require "prawn/document/span"
-require "prawn/document/snapshot"
-require "prawn/document/graphics_state"
+
+require_relative "document/bounding_box"
+require_relative "document/column_box"
+require_relative "document/internals"
+require_relative "document/span"
+require_relative "document/graphics_state"
 
 module Prawn
 
@@ -52,9 +51,8 @@ module Prawn
   #
   class Document
     include Prawn::Document::Internals
-    include Prawn::Core::Annotations
-    include Prawn::Core::Destinations
-    include Prawn::Document::Snapshot
+    include PDF::Core::Annotations
+    include PDF::Core::Destinations
     include Prawn::Document::GraphicsState
     include Prawn::Document::Security
     include Prawn::Text
@@ -63,6 +61,16 @@ module Prawn
     include Prawn::Stamp
     include Prawn::SoftMask
 
+    # @group Extension API
+
+    # NOTE: We probably need to rethink the options validation system, but this
+    # constant temporarily allows for extensions to modify the list.
+
+    VALID_OPTIONS = [:page_size, :page_layout, :margin, :left_margin,
+                     :right_margin, :top_margin, :bottom_margin, :skip_page_creation,
+                     :compress, :skip_encoding, :background, :info,
+                     :text_formatter, :print_scaling]
+
     # Any module added to this array will be included into instances of
     # Prawn::Document at the per-object level.  These will also be inherited by
     # any subclasses.
@@ -83,14 +91,28 @@ module Prawn
     #     party!
     #   end
     #
+    #
     def self.extensions
       @extensions ||= []
     end
 
-    def self.inherited(base) #:nodoc:
+    # @private
+    def self.inherited(base) 
       extensions.each { |e| base.extensions << e }
     end
 
+    # @group Stable Attributes
+
+    attr_accessor :margin_box
+    attr_reader   :margins, :y
+    attr_accessor :page_number
+
+    # @group Extension Attributes
+
+    attr_accessor :text_formatter
+
+    # @group Stable API
+
     # Creates and renders a PDF document.
     #
     # When using the implicit block form, Prawn will evaluate the block
@@ -135,11 +157,10 @@ module Prawn
     # <tt>:bottom_margin</tt>:: Sets the bottom margin in points [0.5 inch]
     # <tt>:skip_page_creation</tt>:: Creates a document without starting the first page [false]
     # <tt>:compress</tt>:: Compresses content streams before rendering them [false]
-    # <tt>:optimize_objects</tt>:: Reduce number of PDF objects in output, at expense of render time [false]
     # <tt>:background</tt>:: An image path to be used as background on all pages [nil]
     # <tt>:background_scale</tt>:: Backgound image scale [1] [nil]
     # <tt>:info</tt>:: Generic hash allowing for custom metadata properties [nil]
-    # <tt>:template</tt>:: The path to an existing PDF file to use as a template [nil]
+    # <tt>:text_formatter</tt>: The text formatter to use for <tt>:inline_format</tt>ted text [Prawn::Text::Formatted::Parser]
     #
     # Setting e.g. the :margin to 100 points and the :left_margin to 50 will result in margins
     # of 100 points on every side except for the left, where it will be 50.
@@ -173,19 +194,18 @@ module Prawn
     def initialize(options={},&block)
       options = options.dup
 
-      Prawn.verify_options [:page_size, :page_layout, :margin, :left_margin,
-        :right_margin, :top_margin, :bottom_margin, :skip_page_creation,
-        :compress, :skip_encoding, :background, :info,
-        :optimize_objects, :template], options
+      Prawn.verify_options VALID_OPTIONS, options
 
       # need to fix, as the refactoring breaks this
       # raise NotImplementedError if options[:skip_page_creation]
 
       self.class.extensions.reverse_each { |e| extend e }
-      @internal_state = Prawn::Core::DocumentState.new(options)
+      @internal_state = PDF::Core::DocumentState.new(options)
       @internal_state.populate_pages_from_store(self)
       min_version(state.store.min_version) if state.store.min_version
 
+      min_version(1.6) if options[:print_scaling] == :none
+
       @background = options[:background]
       @background_scale = options[:background_scale] || 1
       @font_size  = 12
@@ -195,19 +215,12 @@ module Prawn
 
       @page_number = 0
 
+      @text_formatter = options.delete(:text_formatter) || Text::Formatted::Parser
+
       options[:size] = options.delete(:page_size)
       options[:layout] = options.delete(:page_layout)
 
-      if options[:template]
-        fresh_content_streams(options)
-        go_to_page(1)
-      else
-        if options[:skip_page_creation] || options[:template]
-          start_new_page(options.merge(:orphan => true))
-        else
-          start_new_page(options)
-        end
-      end
+      initialize_first_page(options)
 
       @bounding_box = @margin_box
 
@@ -216,18 +229,7 @@ module Prawn
       end
     end
 
-    attr_accessor :margin_box
-    attr_reader   :margins, :y
-    attr_writer   :font_size
-    attr_accessor :page_number
-
-    def state
-      @internal_state
-    end
-
-    def page
-      state.page
-    end
+    # @group Stable API
 
     # Creates and advances to a new page in the document.
     #
@@ -239,14 +241,6 @@ module Prawn
     #   pdf.start_new_page(:left_margin => 50, :right_margin => 50)
     #   pdf.start_new_page(:margin => 100)
     #
-    # A template for a page can be specified by pointing to the path of and existing pdf.
-    # One can also specify which page of the template which defaults otherwise to 1.
-    #
-    #  pdf.start_new_page(:template => multipage_template.pdf, :template_page => 2)
-    #
-    # Note: templates get indexed by either the object_id of the filename or stream
-    # entered so that if you reuse the same template multiple times be sure to use the
-    # same instance for more efficient use of resources and smaller rendered pdfs.
     def start_new_page(options = {})
       if last_page = state.page
         last_page_size    = last_page.size
@@ -258,14 +252,13 @@ module Prawn
                       :layout  => options[:layout] || last_page_layout,
                       :margins => last_page_margins}
       if last_page
-        new_graphic_state = last_page.graphic_state.dup
+        new_graphic_state = last_page.graphic_state.dup  if last_page.graphic_state
         #erase the color space so that it gets reset on new page for fussy pdf-readers
-        new_graphic_state.color_space = {}
+        new_graphic_state.color_space = {} if new_graphic_state
         page_options.merge!(:graphic_state => new_graphic_state)
       end
-      merge_template_options(page_options, options) if options[:template]
 
-      state.page = Prawn::Core::Page.new(self, page_options)
+      state.page = PDF::Core::Page.new(self, page_options)
 
       apply_margin_options(options)
       generate_margin_box
@@ -276,8 +269,7 @@ module Prawn
         @bounding_box = @margin_box
       end
 
-      state.page.new_content_stream if options[:template]
-      use_graphic_settings(options[:template])
+      use_graphic_settings
 
       unless options[:orphan]
         state.insert_page(state.page, @page_number)
@@ -354,19 +346,26 @@ module Prawn
       self.y = original_y
     end
 
-    # Renders the PDF document to string
+    # Renders the PDF document to string.
+    # Pass an open file descriptor to render to file.
     #
-    def render
-      output = StringIO.new
+    def render(output = StringIO.new)
+      if output.instance_of?(StringIO)
+        output.set_encoding(::Encoding::ASCII_8BIT)
+      end
       finalize_all_page_contents
 
       render_header(output)
       render_body(output)
       render_xref(output)
       render_trailer(output)
-      str = output.string
-      str.force_encoding("ASCII-8BIT") if str.respond_to?(:force_encoding)
-      str
+      if output.instance_of?(StringIO)
+        str = output.string
+        str.force_encoding(::Encoding::ASCII_8BIT)
+        return str
+      else
+        return nil
+      end
     end
 
     # Renders the PDF document to file.
@@ -374,8 +373,7 @@ module Prawn
     #   pdf.render_file "foo.pdf"
     #
     def render_file(filename)
-      Kernel.const_defined?("Encoding") ? mode = "wb:ASCII-8BIT" : mode = "wb"
-      File.open(filename,mode) { |f| f << render }
+      File.open(filename, "wb") { |f| render(f) }
     end
 
     # The bounds method returns the current bounding box you are currently in,
@@ -411,6 +409,7 @@ module Prawn
 
     # Returns the innermost non-stretchy bounding box.
     #
+    # @private
     def reference_bounds
       @bounding_box.reference_bounds
     end
@@ -496,47 +495,6 @@ module Prawn
       bounds.indent(left, right, &block)
     end
 
-
-    def mask(*fields) # :nodoc:
-     # Stores the current state of the named attributes, executes the block, and
-     # then restores the original values after the block has executed.
-     # -- I will remove the nodoc if/when this feature is a little less hacky
-      stored = {}
-      fields.each { |f| stored[f] = send(f) }
-      yield
-      fields.each { |f| send("#{f}=", stored[f]) }
-    end
-
-    # Attempts to group the given block vertically within the current context.
-    # First attempts to render it in the current position on the current page.
-    # If that attempt overflows, it is tried anew after starting a new context
-    # (page or column). Returns a logically true value if the content fits in
-    # one page/column, false if a new page or column was needed.
-    #
-    # Raises CannotGroup if the provided content is too large to fit alone in
-    # the current page or column.
-    #
-    def group(second_attempt=false)
-      old_bounding_box = @bounding_box
-      @bounding_box = SimpleDelegator.new(@bounding_box)
-
-      def @bounding_box.move_past_bottom
-        raise RollbackTransaction
-      end
-
-      success = transaction { yield }
-
-      @bounding_box = old_bounding_box
-
-      unless success
-        raise Prawn::Errors::CannotGroup if second_attempt
-        old_bounding_box.move_past_bottom
-        group(second_attempt=true) { yield }
-      end
-
-      success
-    end
-
     # Places a text box on specified pages for page numbering.  This should be called
     # towards the end of document creation, after all your content is already in
     # place.  In your template string, <page> refers to the current page, and
@@ -609,6 +567,42 @@ module Prawn
       end
     end
 
+    # Returns true if content streams will be compressed before rendering,
+    # false otherwise
+    #
+    def compression_enabled?
+      !!state.compress
+    end
+
+    # @group Experimental API
+
+    # Attempts to group the given block vertically within the current context.
+    # First attempts to render it in the current position on the current page.
+    # If that attempt overflows, it is tried anew after starting a new context
+    # (page or column). Returns a logically true value if the content fits in
+    # one page/column, false if a new page or column was needed.
+    #
+    # Raises CannotGroup if the provided content is too large to fit alone in
+    # the current page or column.
+    #
+    # @private
+    def group(*a, &b)
+      raise NotImplementedError, 
+        "Document#group has been disabled because its implementation "+
+        "lead to corrupted documents whenever a page boundary was "+
+        "crossed. We will try to work on reimplementing it in a "+
+        "future release"
+    end
+
+    # @private
+    def transaction
+      raise NotImplementedError, 
+        "Document#transaction has been disabled because its implementation "+
+        "lead to corrupted documents whenever a page boundary was "+
+        "crossed. We will try to work on reimplementing it in a "+
+        "future release"
+    end
+
     # Provides a way to execute a block of code repeatedly based on a
     # page_filter.
     #
@@ -634,23 +628,45 @@ module Prawn
       end
     end
 
+    # @private
+   
+    def mask(*fields) 
+     # Stores the current state of the named attributes, executes the block, and
+     # then restores the original values after the block has executed.
+     # -- I will remove the nodoc if/when this feature is a little less hacky
+      stored = {}
+      fields.each { |f| stored[f] = send(f) }
+      yield
+      fields.each { |f| send("#{f}=", stored[f]) }
+    end
 
-    # Returns true if content streams will be compressed before rendering,
-    # false otherwise
-    #
-    def compression_enabled?
-      !!state.compress
+    # @group Extension API
+
+    def initialize_first_page(options)
+      if options[:skip_page_creation]
+        start_new_page(options.merge(:orphan => true))
+      else
+        start_new_page(options)
+      end
     end
 
-    private
+    ## Internals. Don't depend on them!
 
-    def merge_template_options(page_options, options)
-      object_id = state.store.import_page(options[:template], options[:template_page] || 1)
-      page_options.merge!(:object_id => object_id, :page_template => true)
+    # @private
+    def state
+      @internal_state
     end
 
+    # @private
+    def page
+      state.page
+    end
+
+    private
+
+
     # setting override_settings to true ensures that a new graphic state does not end up using
-    # previous settings especially from imported template streams
+    # previous settings.
     def use_graphic_settings(override_settings = false)
       set_fill_color if current_fill_color != "000000" || override_settings
       set_stroke_color if current_stroke_color != "000000" || override_settings
@@ -680,9 +696,7 @@ module Prawn
 
       # we must update bounding box if not flowing from the previous page
       #
-      # FIXME: This may have a bug where the old margin is restored
-      # when the bounding box exits.
-      @bounding_box = @margin_box if old_margin_box == @bounding_box
+      @bounding_box = @margin_box unless @bounding_box && @bounding_box.parent    
     end
 
     def apply_margin_options(options)
@@ -703,5 +717,9 @@ module Prawn
          end
       end
     end
+
+    def font_metric_cache #:nodoc:
+      @font_metric_cache ||= FontMetricCache.new( self )
+    end
   end
 end