prawn-core 0.6.3 → 0.7.1

data/lib/prawn/font/afm.rb

@@ -20,9 +20,9 @@ module Prawn
         end
       end
 
-      attr_reader :attributes
+      attr_reader :attributes #:nodoc:
 
-      def initialize(document, name, options={})
+      def initialize(document, name, options={}) #:nodoc:
         unless BUILT_INS.include?(name)
           raise Prawn::Errors::UnknownFont, "#{name} is not a known font."
         end
@@ -45,15 +45,14 @@ module Prawn
         @line_gap  = Float(bbox[3] - bbox[1]) - (@ascender - @descender)
       end
 
+      # The font bbox, as an array of integers
+      #
       def bbox
         @bbox ||= @attributes['fontbbox'].split(/\s+/).map { |e| Integer(e) }
       end
 
-      # calculates the width of the supplied string.
-      #
-      # String *must* be encoded as WinAnsi
-      #
-      def compute_width_of(string, options={})
+      # NOTE: String *must* be encoded as WinAnsi
+      def compute_width_of(string, options={}) #:nodoc:
         scale = (options[:size] || size) / 1000.0
 
         if options[:kerning]
@@ -65,6 +64,8 @@ module Prawn
         end
       end
 
+      # Returns true if the font has kerning data, false otherwise
+      #
       def has_kerning_data?
         @kern_pairs.any?
       end
@@ -72,6 +73,7 @@ module Prawn
       # built-in fonts only work with winansi encoding, so translate the
       # string. Changes the encoding in-place, so the argument itself
       # is replaced with a string in WinAnsi encoding.
+      #
       def normalize_encoding(text)
         enc = Prawn::Encoding::WinAnsi.new
         text.unpack("U*").collect { |i| enc[i] }.pack("C*")
@@ -88,6 +90,7 @@ module Prawn
       # the string itself (or an array, if kerning is performed).
       #
       # The +text+ parameter must be in WinAnsi encoding (cp1252).
+      #
       def encode_text(text, options={})
         [[0, options[:kerning] ? kern(text) : text]]
       end

data/lib/prawn/font/ttf.rb

@@ -22,9 +22,8 @@ module Prawn
         @line_gap         = Integer(@ttf.line_gap * scale_factor)
       end
 
-      # +string+ must be UTF8-encoded.
-      #
-      def compute_width_of(string, options={})
+      # NOTE: +string+ must be UTF8-encoded.
+      def compute_width_of(string, options={}) #:nodoc:
         scale = (options[:size] || size) / 1000.0
         if options[:kerning]
           kern(string).inject(0) do |s,r|
@@ -40,11 +39,14 @@ module Prawn
           end * scale
         end
       end   
-      
+     
+      # The font bbox, as an array of integers
+      # 
       def bbox
         @bbox ||= @ttf.bbox.map { |i| Integer(i * scale_factor) }
       end
 
+      # Returns true if the font has kerning data, false otherwise
       def has_kerning_data?
         @has_kerning_data 
       end

data/lib/prawn/font.rb

@@ -113,21 +113,18 @@ module Prawn
     # font will be embedded twice. Since we do font subsetting, this double
     # embedding won't be catastrophic, just annoying.
     # ++
-    #
-    def find_font(name, options={}) #:nodoc:
-      if font_families.key?(name)
-        family, name = name, font_families[name][options[:style] || :normal]
-
-        if name.is_a?(Hash)
-          options = options.merge(name)
-          name = options[:file]
-        end
-      end
-
-      key = "#{name}:#{options[:font] || 0}"
-      font_registry[key] ||= Font.load(self, name, options.merge(:family => family))
-    end
-
+    def find_font(name, options={}) #:nodoc: 
+      if font_families.key?(name) 
+        family, name = name, font_families[name][options[:style] || :normal] 
+        if name.is_a?(Hash) 
+          options = options.merge(name) 
+          name = options[:file] 
+        end 
+      end 
+      key = "#{name}:#{options[:font] || 0}" 
+      font_registry[key] ||= Font.load(self, name, options.merge(:family => family)) 
+    end 
+    
     # Hash of Font objects keyed by names
     #
     def font_registry #:nodoc:
@@ -210,6 +207,10 @@ module Prawn
     # The options hash used to initialize the font
     attr_reader :options
 
+    # Shortcut interface for constructing a font object.  Filenames of the form
+    # *.ttf will call Font::TTF.new, *.dfont Font::DFont.new, and anything else
+    # will be passed through to Font::AFM.new()
+    #
     def self.load(document,name,options={})
       case name
       when /\.ttf$/   then TTF.new(document, name, options)
@@ -231,26 +232,24 @@ module Prawn
       @references = {}
     end
 
+    # The size of the font ascender in PDF points 
+    #
     def ascender
       @ascender / 1000.0 * size
     end
 
+    # The size of the font descender in PDF points
+    #
     def descender
-      @descender / 1000.0 * size
+      -@descender / 1000.0 * size
     end
 
+    # The size of the recommended gap between lines of text in PDF points
+    #
     def line_gap
       @line_gap / 1000.0 * size
     end
 
-    def identifier_for(subset)
-      "#{@identifier}.#{subset}"
-    end
-
-    def inspect
-      "#{self.class.name}< #{name}: #{size} >"
-    end
-
     # Normalizes the encoding of the string to an encoding supported by the
     # font. The string is expected to be UTF-8 going in. It will be re-encoded
     # and the new string will be returned. For an in-place (destructive)
@@ -261,10 +260,13 @@ module Prawn
 
     # Destructive version of normalize_encoding; normalizes the encoding of a
     # string in place.
+    #
     def normalize_encoding!(str)
       str.replace(normalize_encoding(str))
     end
 
+    # Gets height of current font in PDF points at the given font size
+    #
     def height_at(size)
       @normalized_height ||= (@ascender - @descender + @line_gap) / 1000.0
       @normalized_height * size
@@ -285,6 +287,14 @@ module Prawn
       @document.page_fonts.merge!(identifier_for(subset) => @references[subset])
     end
 
+    def identifier_for(subset) #:nodoc:
+      "#{@identifier}.#{subset}"
+    end
+
+    def inspect #:nodoc:
+      "#{self.class.name}< #{name}: #{size} >"
+    end
+
     private
 
     def size

data/lib/prawn/graphics/cap_style.rb

@@ -9,12 +9,15 @@
 module Prawn
   module Graphics
     module CapStyle
-      # Sets the cap_style for stroked lines and curves
-      #
 
       CAP_STYLES = { :butt => 0, :round => 1, :projecting_square => 2 }
       
+      # Sets the cap style for stroked lines and curves
+      #
       # style is one of :butt, :round, or :projecting_square
+      #
+      # NOTE: If this method is never called, :butt will be used by default.
+      #
       def cap_style(style=nil)
         return @cap_style || :butt if style.nil?
 

data/lib/prawn/graphics/color.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8   
+# encoding: utf-8
 
 # color.rb : Implements color handling
 #
@@ -8,41 +8,41 @@
 #
 module Prawn
   module Graphics
-    module Color   
-      
-      # Sets the fill color.  
+    module Color
+
+      # Sets the fill color.
       #
-      # If a single argument is provided, it should be a 6 digit HTML color 
+      # If a single argument is provided, it should be a 6 digit HTML color
       # code.
-      # 
+      #
       #   pdf.fill_color "f0ffc1"
       #
       # If 4 arguments are provided, the color is assumed to be a CMYK value
       # Values range from 0 - 100.
-      # 
+      #
       #   pdf.fill_color 0, 99, 95, 0
       #
-      def fill_color(*color)  
-        return @fill_color if color.empty? 
-        @fill_color = process_color(*color) 
+      def fill_color(*color)
+        return @fill_color if color.empty?
+        @fill_color = process_color(*color)
         set_fill_color
-      end 
+      end
 
-      alias_method :fill_color=, :fill_color                                                                     
+      alias_method :fill_color=, :fill_color
 
       # Sets the line stroking color.  6 digit HTML color codes are used.
       #
-      # If a single argument is provided, it should be a 6 digit HTML color 
+      # If a single argument is provided, it should be a 6 digit HTML color
       # code.
-      # 
+      #
       #   pdf.stroke_color "f0ffc1"
       #
       # If 4 arguments are provided, the color is assumed to be a CMYK value
       # Values range from 0 - 100.
-      # 
+      #
       #   pdf.stroke_color 0, 99, 95, 0
       #
-      def stroke_color(*color)   
+      def stroke_color(*color)
         return @stroke_color if color.empty?
         @stroke_color = process_color(*color)
         set_stroke_color
@@ -57,30 +57,30 @@ module Prawn
       #    fill_and_stroke_some_method(*args) #=> some_method(*args); fill_and_stroke
       #
       def method_missing(id,*args,&block)
-        case(id.to_s) 
+        case(id.to_s)
         when /^fill_and_stroke_(.*)/
           send($1,*args,&block); fill_and_stroke
         when /^stroke_(.*)/
-          send($1,*args,&block); stroke 
+          send($1,*args,&block); stroke
         when /^fill_(.*)/
           send($1,*args,&block); fill
         else
           super
         end
-      end   
-      
+      end
+
       module_function
-        
-      # Converts RGB value array to hex string suitable for use with fill_color 
-      # and stroke_color  
+
+      # Converts RGB value array to hex string suitable for use with fill_color
+      # and stroke_color
       #
       #   >> Prawn::Graphics::Color.rgb2hex([255,120,8])
-      #   => "ff7808"     
+      #   => "ff7808"
       #
       def rgb2hex(rgb)
         rgb.map { |e| "%02x" % e }.join
-      end  
-       
+      end
+
       # Converts hex string into RGB value array:
       #
       #  >> Prawn::Graphics::Color.hex2rgb("ff7808")
@@ -89,53 +89,113 @@ module Prawn
       def hex2rgb(hex)
         r,g,b = hex[0..1], hex[2..3], hex[4..5]
         [r,g,b].map { |e| e.to_i(16) }
-      end 
-      
+      end
+
       private
-      
-      def process_color(*color)   
+
+      def process_color(*color)
         case(color.size)
-        when 1    
-          color[0]    
+        when 1
+          color[0]
         when 4
           color
         else
-          raise ArgumentError, 'wrong number of arguments supplied'    
-        end
-      end  
-      
-      def set_fill_color             
-        case @fill_color
-        when String
-          r,g,b = hex2rgb(@fill_color)
-          add_content "%.3f %.3f %.3f rg" % 
-             [r / 255.0, g / 255.0, b / 255.0]
-        when Array     
-          c,m,y,k = *@fill_color
-          add_content "%.3f %.3f %.3f %.3f k" % 
-            [c / 100.0, m / 100.0, y / 100.0, k / 100.0]
+          raise ArgumentError, 'wrong number of arguments supplied'
         end
       end
 
-      def set_stroke_color       
-        case @stroke_color
+      def color_type(color)
+        case color
         when String
-          r,g,b = hex2rgb(@stroke_color)
-          add_content "%.3f %.3f %.3f RG" %  
-            [r / 255.0, g / 255.0, b / 255.0]
+          :RGB
         when Array
-          c,m,y,k = *@stroke_color
-          add_content "%.3f %.3f %.3f %.3f K" %  
-            [c / 100.0, m / 100.0, y / 100.0, k / 100.0]
+          :CMYK
+        end
+      end
+
+      def normalize_color(color)
+        case color_type(color)
+        when :RGB
+          r,g,b = hex2rgb(color)
+          [r / 255.0, g / 255.0, b / 255.0]
+        when :CMYK
+          c,m,y,k = *color
+          [c / 100.0, m / 100.0, y / 100.0, k / 100.0]
         end
-      end                                       
+      end
+
+      def color_to_s(color)
+        normalize_color(color).map { |c| '%.3f' % c }.join(' ')
+      end
 
-      def update_colors 
+      def color_space(color)
+        case color_type(color)
+        when :RGB
+          :DeviceRGB
+        when :CMYK
+          :DeviceCMYK
+        end
+      end
+
+      COLOR_SPACES = [:DeviceRGB, :DeviceCMYK, :Pattern]
+
+      def set_color_space(type, color_space)
+        # don't set the same color space again
+        return if @color_space[type] == color_space
+        @color_space[type] = color_space
+
+        unless COLOR_SPACES.include?(color_space)
+          raise ArgumentError, "unknown color space: '#{color_space}'"
+        end
+
+        operator = case type
+        when :fill
+          'cs'
+        when :stroke
+          'CS'
+        else
+          raise ArgumentError, "unknown type '#{type}'"
+        end
+
+        add_content "/#{color_space} #{operator}"
+      end
+
+      def set_color(type, color, options = {})
+        operator = case type
+        when :fill
+          'scn'
+        when :stroke
+          'SCN'
+        else
+          raise ArgumentError, "unknown type '#{type}'"
+        end
+
+        if options[:pattern]
+          set_color_space type, :Pattern
+          add_content "/#{color} #{operator}"
+        else
+          set_color_space type, color_space(color)
+          color = color_to_s(color)
+          add_content "#{color} #{operator}"
+        end
+      end
+
+      def set_fill_color
+        set_color :fill, @fill_color
+      end
+
+      def set_stroke_color
+        set_color :stroke, @stroke_color
+      end
+
+      def update_colors
+        @color_space  = {}
         @fill_color   ||= "000000"
         @stroke_color ||= "000000"
         set_fill_color
         set_stroke_color
-      end     
+      end
     end
   end
 end
+

data/lib/prawn/graphics/dash.rb

@@ -40,13 +40,15 @@ module Prawn
       
       alias_method :dash=, :dash
 
-      # Restores solid stroking
+      # Stops dashing, restoring solid stroked lines and curves
+      #
       def undash
         @dash = undash_hash
         write_stroke_dash
       end
       
-      # Returns true iff the stroke is dashed
+      # Returns when stroke is dashed, false otherwise
+      #
       def dashed?
         dash != undash_hash
       end

data/lib/prawn/graphics/join_style.rb

@@ -9,12 +9,15 @@
 module Prawn
   module Graphics
     module JoinStyle
-      # Sets the join_style for stroked lines and curves
-      #
-
       JOIN_STYLES = { :miter => 0, :round => 1, :bevel => 2 }
       
+      # Sets the join style for stroked lines and curves
+      #
       # style is one of :miter, :round, or :bevel
+      #
+      # NOTE: if this method is never called, :miter will be used for join style
+      # throughout the document
+      #
       def join_style(style=nil)
         return @join_style || :miter if style.nil?
 

data/lib/prawn/graphics/transparency.rb

@@ -9,35 +9,61 @@
 
 module Prawn
   module Graphics
+
+    # The Prawn::Transparency module is used to place transparent
+    # content on the page. It has the capacity for separate
+    # transparency values for stroked content and all other content.
+    #
+    # Example:
+    #   # both the fill and stroke will be at 50% opacity
+    #   pdf.transparent(0.5) do
+    #     pdf.text("hello world")
+    #     pdf.fill_and_stroke_circle_at([x, y], :radius => 25)
+    #   end
+    #
+    #   # the fill will be at 50% opacity, but the stroke will
+    #   # be at 75% opacity
+    #   pdf.transparent(0.5, 0.75) do
+    #     pdf.text("hello world")
+    #     pdf.fill_and_stroke_circle_at([x, y], :radius => 25)
+    #   end
+    #
     module Transparency
 
+      # Sets the <tt>opacity</tt> and <tt>stroke_opacity</tt> for all
+      # the content within the <tt>block</tt>
+      # If <tt>stroke_opacity</tt> is not provided, then it takes on
+      # the same value as <tt>opacity</tt>
+      #
+      # Valid ranges for both paramters are 0.0 to 1.0
+      #
+      # Example:
+      #   # both the fill and stroke will be at 50% opacity
+      #   pdf.transparent(0.5) do
+      #     pdf.text("hello world")
+      #     pdf.fill_and_stroke_circle_at([x, y], :radius => 25)
+      #   end
+      #
+      #   # the fill will be at 50% opacity, but the stroke will
+      #   # be at 75% opacity
+      #   pdf.transparent(0.5, 0.75) do
+      #     pdf.text("hello world")
+      #     pdf.fill_and_stroke_circle_at([x, y], :radius => 25)
+      #   end
+      #
       def transparent(opacity, stroke_opacity=opacity, &block)
         min_version(1.4)
 
-        key = "#{opacity}_#{stroke_opacity}"
-
-        if opacity_dictionary_registry[key]
-          opacity_dictionary =  opacity_dictionary_registry[key][:obj]
-          opacity_dictionary_name =  opacity_dictionary_registry[key][:name]
-        else
-          opacity_dictionary = ref!(:Type => :ExtGState,
-                                    :CA   => stroke_opacity,
-                                    :ca   => opacity
-                                    )
-
-          opacity_dictionary_name = "Tr#{next_opacity_dictionary_id}"
-          opacity_dictionary_registry[key] = { :name => opacity_dictionary_name, 
-                                               :obj  => opacity_dictionary }
-        end
-
-        page_ext_gstates.merge!(opacity_dictionary_name => opacity_dictionary)
+        opacity        = [[opacity, 0.0].max, 1.0].min
+        stroke_opacity = [[stroke_opacity, 0.0].max, 1.0].min
 
         # push a new graphics context onto the graphics context stack
         add_content "q"
-        add_content "/#{opacity_dictionary_name} gs"
+        add_content "/#{opacity_dictionary_name(opacity, stroke_opacity)} gs"
 
         yield if block_given?
 
+        # restore the previous graphics context
         add_content "Q"
       end
 
@@ -51,6 +77,27 @@ module Prawn
         opacity_dictionary_registry.length + 1
       end
 
+      def opacity_dictionary_name(opacity, stroke_opacity)
+        key = "#{opacity}_#{stroke_opacity}"
+
+        if opacity_dictionary_registry[key]
+          dictionary =  opacity_dictionary_registry[key][:obj]
+          dictionary_name =  opacity_dictionary_registry[key][:name]
+        else
+          dictionary = ref!(:Type => :ExtGState,
+                                    :CA   => stroke_opacity,
+                                    :ca   => opacity
+                                    )
+
+          dictionary_name = "Tr#{next_opacity_dictionary_id}"
+          opacity_dictionary_registry[key] = { :name => dictionary_name, 
+                                               :obj  => dictionary }
+        end
+
+        page_ext_gstates.merge!(dictionary_name => dictionary)
+        dictionary_name
+      end
+
     end
   end
 end

data/lib/prawn/images/jpg.rb

@@ -22,7 +22,7 @@ module Prawn
 
       # Process a new JPG image
       #
-      # <tt>:data</tt>:: A string containing a full PNG file
+      # <tt>:data</tt>:: A binary string of JPEG data
       #
       def initialize(data)
         data = StringIO.new(data.dup)

data/lib/prawn/images/png.rb

@@ -25,7 +25,7 @@ module Prawn
 
       # Process a new PNG image
       #
-      # <tt>data</tt>:: A string containing a full PNG file
+      # <tt>data</tt>:: A binary string of PNG data
       #
       def initialize(data)
         data = StringIO.new(data.dup)

data/lib/prawn/object_store.rb

@@ -6,7 +6,7 @@
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
 module Prawn
-  class ObjectStore
+  class ObjectStore #:nodoc:
     include Enumerable
 
     def initialize(info={})
@@ -59,5 +59,34 @@ module Prawn
     end
     alias_method :length, :size
 
+    def compact
+      # Clear live markers
+      each { |o| o.live = false }
+
+      # Recursively mark reachable objects live, starting from the roots
+      # (the only objects referenced in the trailer)
+      root.mark_live
+      info.mark_live
+
+      # Renumber live objects to eliminate gaps (shrink the xref table)
+      if @objects.any?{ |_, o| !o.live }
+        new_id = 1
+        new_objects = {}
+        new_identifiers = []
+
+        each do |obj|
+          if obj.live
+            obj.identifier = new_id
+            new_objects[new_id] = obj
+            new_identifiers << new_id
+            new_id += 1
+          end
+        end
+
+        @objects = new_objects
+        @identifiers = new_identifiers
+      end
+    end
+
   end
 end