prawn 0.12.0 → 0.13.0

data/lib/prawn/text/formatted/parser.rb

@@ -13,8 +13,7 @@ module Prawn
     module Formatted
 
       class Parser
-
-        def self.to_array(string)
+        PARSER_REGEX = begin
           regex_string = "\n|" +
                          "<b>|</b>|" +
                          "<i>|</i>|" +
@@ -29,8 +28,11 @@ module Prawn
                          "<em>|</em>|" +
                          "<a[^>]*>|</a>|" +
                          "[^<\n]+"
-          regex = Regexp.new(regex_string, Regexp::MULTILINE)
-          tokens = string.scan(regex)
+          Regexp.new(regex_string, Regexp::MULTILINE)
+        end
+
+        def self.format(string, *args)
+          tokens = string.gsub(/<br\s*\/?>/, "\n").scan(PARSER_REGEX)
           self.array_from_tokens(tokens)
         end
 
@@ -122,10 +124,11 @@ module Prawn
           colors = []
           link = nil
           anchor = nil
+          local = nil
           fonts = []
           sizes = []
           character_spacings = []
-          
+
           while token = tokens.shift
             case token
             when "<b>", "<strong>"
@@ -155,6 +158,7 @@ module Prawn
             when "</link>", "</a>"
               link = nil
               anchor = nil
+              local = nil
             when "</color>"
               colors.pop
             when "</font>"
@@ -168,6 +172,9 @@ module Prawn
 
                 matches = /anchor="([^"]*)"/.match(token) || /anchor='([^']*)'/.match(token)
                 anchor = matches[1] unless matches.nil?
+
+                matches = /local="([^"]*)"/.match(token) || /local='([^']*)'/.match(token)
+                local = matches[1] unless matches.nil?
               elsif token =~ /^<color[^>]*>$/
                 matches = /rgb="#?([^"]*)"/.match(token) || /rgb='#?([^']*)'/.match(token)
                 colors << matches[1] if matches
@@ -179,7 +186,7 @@ module Prawn
                 # intend to support rgb="#ffffff" or rgb='#ffffff',
                 # r="255" g="255" b="255" or r='255' g='255' b='255',
                 # and c="100" m="100" y="100" k="100" or
-                # c='100' m='100' y='100' k='100' 
+                # c='100' m='100' y='100' k='100'
                 # color = { :rgb => "#ffffff" }
                 # color = { :r => 255, :g => 255, :b => 255 }
                 # color = { :c => 100, :m => 100, :y => 100, :k => 100 }
@@ -197,6 +204,7 @@ module Prawn
                 array << { :text => string,
                            :styles => styles.dup,
                            :color => colors.last,
+                           :local => local,
                            :link => link,
                            :anchor => anchor,
                            :font => fonts.last,

data/lib/prawn/text/formatted/wrap.rb

@@ -0,0 +1,151 @@
+require_relative "line_wrap"
+require_relative "arranger"
+
+module Prawn
+  module Text
+    module Formatted #:nodoc:
+      module Wrap #:nodoc:
+
+        def initialize(array, options)
+          @line_wrap = Prawn::Text::Formatted::LineWrap.new
+          @arranger = Prawn::Text::Formatted::Arranger.new(@document,
+            :kerning => options[:kerning])
+        end
+
+
+        # See the developer documentation for PDF::Core::Text#wrap
+        #
+        # Formatted#wrap should set the following variables:
+        #   <tt>@line_height</tt>::
+        #        the height of the tallest fragment in the last printed line
+        #   <tt>@descender</tt>::
+        #        the descender height of the tallest fragment in the last
+        #        printed line
+        #   <tt>@ascender</tt>::
+        #        the ascender heigth of the tallest fragment in the last
+        #        printed line
+        #   <tt>@baseline_y</tt>::
+        #       the baseline of the current line
+        #   <tt>@nothing_printed</tt>::
+        #       set to true until something is printed, then false
+        #   <tt>@everything_printed</tt>::
+        #       set to false until everything printed, then true
+        #
+        # Returns any formatted text that was not printed
+        #
+        def wrap(array) #:nodoc:
+          initialize_wrap(array)
+
+          stop = false
+          while !stop
+            # wrap before testing if enough height for this line because the
+            # height of the highest fragment on this line will be used to
+            # determine the line height
+            @line_wrap.wrap_line(:document => @document,
+                                 :kerning => @kerning,
+                                 :width => available_width,
+                                 :arranger => @arranger)
+
+            if enough_height_for_this_line?
+              move_baseline_down
+              print_line
+            else
+              stop = true
+            end
+
+            stop ||= @single_line || @arranger.finished?
+          end
+          @text = @printed_lines.join("\n")
+          @everything_printed = @arranger.finished?
+          @arranger.unconsumed
+        end
+
+        private
+
+        def print_line
+          @nothing_printed = false
+          printed_fragments = []
+          fragments_this_line = []
+
+          word_spacing = word_spacing_for_this_line
+          while fragment = @arranger.retrieve_fragment
+            fragment.word_spacing = word_spacing
+            if fragment.text == "\n"
+              printed_fragments << "\n" if @printed_lines.last == ""
+              break
+            end
+            printed_fragments << fragment.text
+            fragments_this_line << fragment
+          end
+
+          accumulated_width = 0
+          fragments_this_line.reverse! if @direction == :rtl
+          fragments_this_line.each do |fragment_this_line|
+            fragment_this_line.default_direction = @direction
+            format_and_draw_fragment(fragment_this_line, accumulated_width,
+                                     @line_wrap.width, word_spacing)
+            accumulated_width += fragment_this_line.width
+          end
+
+          if "".respond_to?(:force_encoding)
+            printed_fragments.map! { |s| s.force_encoding("utf-8") }
+          end
+          @printed_lines << printed_fragments.join
+        end
+
+        def word_spacing_for_this_line
+          if @align == :justify &&
+              @line_wrap.space_count > 0 &&
+              !@line_wrap.paragraph_finished?
+            (available_width - @line_wrap.width) / @line_wrap.space_count
+          else
+            0
+          end
+        end
+
+        def enough_height_for_this_line?
+          @line_height = @arranger.max_line_height
+          @descender   = @arranger.max_descender
+          @ascender    = @arranger.max_ascender
+          if @baseline_y == 0
+            diff = @ascender + @descender
+          else
+            diff = @descender + @line_height + @leading
+          end
+          require_relatived_total_height = @baseline_y.abs + diff
+          if require_relatived_total_height > @height + 0.0001
+            # no room for the full height of this line
+            @arranger.repack_unretrieved
+            false
+          else
+            true
+          end
+        end
+
+        def initialize_wrap(array)
+          @text = nil
+          @arranger.format_array = array
+
+          # these values will depend on the maximum value within a given line
+          @line_height = 0
+          @descender   = 0
+          @ascender    = 0
+          @baseline_y  = 0
+
+          @printed_lines = []
+          @nothing_printed = true
+          @everything_printed = false
+        end
+
+        def format_and_draw_fragment(fragment, accumulated_width,
+                                     line_width, word_spacing)
+          @arranger.apply_color_and_font_settings(fragment) do
+            draw_fragment(fragment, accumulated_width,
+                          line_width, word_spacing)
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/prawn/utilities.rb

@@ -0,0 +1,44 @@
+# encoding: utf-8
+
+# utilities.rb : General-purpose utility classes which don't fit anywhere else
+#
+# Copyright August 2012, Alex Dowad. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+require 'thread'
+
+module Prawn
+
+  # Throughout the Prawn codebase, repeated calculations which can benefit from caching are made
+  # In some cases, caching and reusing results can not only save CPU cycles but also greatly
+  #   reduce memory requirements
+  # But at the same time, we don't want to throw away thread safety
+  # We have two interchangeable thread-safe cache implementations:
+
+  class SynchronizedCache
+    # As an optimization, this could access the hash directly on VMs with a global interpreter lock (like MRI)
+    def initialize
+      @cache = {}
+      @mutex = Mutex.new
+    end
+    def [](key)
+      @mutex.synchronize { @cache[key] }
+    end
+    def []=(key,value)
+      @mutex.synchronize { @cache[key] = value }
+    end
+  end
+
+  class ThreadLocalCache
+    def initialize
+      @cache_id = "cache_#{self.object_id}".to_sym
+    end
+    def [](key)
+      (Thread.current[@cache_id] ||= {})[key]
+    end
+    def []=(key,value)
+      (Thread.current[@cache_id] ||= {})[key] = value
+    end
+  end
+end

data/manual/basic_concepts/adding_pages.rb

@@ -0,0 +1,27 @@
+# encoding: utf-8
+#
+# A PDF document is a collection of pages. When we create a new document be it
+# with <code>Document.new</code> or on a <code>Document.generate</code> block
+# one initial page is created for us.
+#
+# Some methods might create new pages automatically like <code>text</code> which
+# will create a new page whenever the text string cannot fit on the current
+# page.
+#
+# But what if you want to go to the next page by yourself? That is easy.
+#
+# Just use the <code>start_new_page</code> method and a shiny new page will be
+# created for you just like in the following snippet.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  text "We are still on the initial page for this example. Now I'll ask " +
+       "Prawn to gently start a new page. Please follow me to the next page."
+  
+  start_new_page
+  
+  text "See. We've left the previous page behind."
+end

data/manual/basic_concepts/basic_concepts.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+#
+# Examples for Prawn basic concepts.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::Example.generate("basic_concepts.pdf", :page_size => "FOLIO") do
+  
+  package "basic_concepts" do |p|
+    
+    p.example "creation", :eval_source => false, :full_source => true
+    p.example "origin"
+    p.example "cursor"
+    p.example "other_cursor_helpers"
+    p.example "adding_pages"
+    p.example "measurement"
+    
+    p.intro do
+      prose("This chapter covers the minimum amount of functionality you'll need to start using Prawn.
+
+      If you are new to Prawn this is the first chapter to read. Once you are comfortable with the concepts shown here you might want to check the Basics section of the Graphics, Bounding Box and Text sections.
+
+      The examples show:")
+
+      list( "How to create new pdf documents in every possible way",
+            "Where the origin for the document coordinates is. What are Bounding Boxes and how they interact with the origin",
+            "How the cursor behaves",
+            "How to start new pages",
+            "What the base unit for measurement and coordinates is and how to use other convenient measures"
+          )
+    end
+  end
+end

data/manual/basic_concepts/creation.rb

@@ -0,0 +1,39 @@
+# encoding: utf-8
+#
+# There are three ways to create a PDF Document in Prawn: creating a new
+# <code>Prawn::Document</code> instance, or using the
+# <code>Prawn::Document.generate</code> method with and without block arguments.
+#
+# The following snippet showcase each way by creating a simple document with
+# some text drawn.
+#
+# When we instantiate the <code>Prawn::Document</code> object the actual pdf
+# document will only be created after we call <code>render_file</code>.
+#
+# The generate method will render the actual pdf object after exiting the block.
+# When we use it without a block argument the provided block is evaluated in the
+# context of a newly created <code>Prawn::Document</code> instance. When we use
+# it with a block argument a <code>Prawn::Document</code> instance is created
+# and passed to the block.
+#
+# The generate method without block arguments requires
+# less typing and defines and renders the pdf document in one shot.
+# Almost all of the examples are coded this way.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+# Assignment
+pdf = Prawn::Document.new
+pdf.text "Hello World"
+pdf.render_file "assignment.pdf"
+
+# Implicit Block
+Prawn::Document.generate("implicit.pdf") do
+  text "Hello World"
+end
+
+# Explicit Block
+Prawn::Document.generate("explicit.pdf") do |pdf|
+  pdf.text "Hello World"
+end

data/manual/basic_concepts/cursor.rb

@@ -0,0 +1,33 @@
+# encoding: utf-8
+#
+# We normally write our documents from top to bottom and it is no different with
+# Prawn. Even if the origin is on the bottom left corner we still fill the page
+# from the top to the bottom. In other words the cursor for inserting content
+# starts on the top of the page.
+#
+# Most of the functions that insert content on the page will start at the
+# current cursor position and proceed to the bottom of the page.
+#
+# The following snippet shows how the cursor behaves when we add some text to
+# the page and demonstrates some of the helpers to manage the cursor position.
+# The <code>cursor</code> method returns the current cursor position.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+  
+  text "the cursor is here: #{cursor}"
+  text "now it is here: #{cursor}"
+  
+  move_down 200
+  text "on the first move the cursor went down to: #{cursor}"
+  
+  move_up 100
+  text "on the second move the cursor went up to: #{cursor}"
+  
+  move_cursor_to 50
+  text "on the last move the cursor went directly to: #{cursor}"
+end

data/manual/basic_concepts/measurement.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+#
+# The base unit in Prawn is the PDF Point. One PDF Point is equal to 1/72 of
+# an inch.
+#
+# There is no need to waste time converting this measures. Prawn provides
+# helpers for converting from other measurements
+# to PDF Points.
+#
+# Just <code>require "prawn/measurement_extensions"</code> and it will mix some
+# helpers onto <code>Numeric</code> for converting common measurement units to
+# PDF Points.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  require "prawn/measurement_extensions"
+  
+  [:mm, :cm, :dm, :m, :in, :yd, :ft].each do |measurement|
+    text "1 #{measurement} in PDF Points: #{1.send(measurement)} pt"
+    move_down 5.mm
+  end
+end

data/manual/basic_concepts/origin.rb

@@ -0,0 +1,38 @@
+# encoding: utf-8
+#
+# This is the most important concept you need to learn about Prawn:
+#
+# PDF documents have the origin <code>[0,0]</code> at the bottom-left corner of
+# the page.
+#
+# A bounding box is a structure which provides boundaries for inserting content.
+# A bounding box also has the property of relocating the origin to its relative
+# bottom-left corner. However, be aware that the location specified when
+# creating a bounding box is its top-left corner, not bottom-left (hence the
+# <code>[100, 300]</code> coordinates below).
+#
+# Even if you never create a bounding box explictly, each document already comes
+# with one called the margin box. This initial bounding box is the one
+# responsible for the document margins.
+#
+# So practically speaking the origin of a page on a default generated document
+# isn't the absolute bottom left corner but the bottom left corner of the margin
+# box.
+#
+# The following snippet strokes a circle on the margin box origin. Then strokes
+# the boundaries of a bounding box and a circle on its origin.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+  
+  stroke_circle [0, 0], 10
+  
+  bounding_box([100, 300], :width => 300, :height => 200) do
+    stroke_bounds
+    stroke_circle [0, 0], 10
+  end
+end