prawn 0.14.0 → 0.15.0

data/lib/prawn/document/column_box.rb

@@ -9,6 +9,8 @@ require_relative "bounding_box"
 module Prawn
   class Document
 
+    # @group Experimental API
+
     # A column box is a bounding box with the additional property that when
     # text flows past the bottom, it will wrap first to another column on the
     # same page, and only flow to the next page when all the columns are

data/lib/prawn/document/graphics_state.rb

@@ -9,7 +9,7 @@
 
 module Prawn
   class Document
-    module GraphicsState
+    module GraphicsState # @private
 
       # Pushes the current graphics state on to the graphics state stack so we
       # can restore it when finished with a change we want to isolate (such as

data/lib/prawn/document/internals.rb

@@ -14,8 +14,8 @@ module Prawn
     # low level PDF functionality as defined by Adobe's specification, chances
     # are you won't need anything you find here.
     #
-    module Internals
-
+    # @private
+    module Internals 
       # Creates a new Prawn::Reference and adds it to the Document's object
       # list.  The +data+ argument is anything that Prawn::PdfObject() can convert.
       #

data/lib/prawn/document/snapshot.rb

@@ -10,8 +10,9 @@ require 'delegate'
 
 module Prawn
   class Document
+    # @private
+    
     module Snapshot
-
       RollbackTransaction = Class.new(StandardError)
 
       # Call this within a +transaction+ block to roll back the transaction and

data/lib/prawn/document/span.rb

@@ -8,6 +8,8 @@
 
 module Prawn
   class Document
+    # @group Stable API
+
     # A span is a special purpose bounding box that allows a column of
     # elements to be positioned relative to the margin_box.
     #

data/lib/prawn/encoding.rb

@@ -5,7 +5,7 @@
 # This is free software. Please see the LICENSE and COPYING files for details.
 #
 module Prawn
-  module Encoding
+  module Encoding # @private
     # Map between unicode and WinAnsiEnoding
     #
     class WinAnsi #:nodoc:

data/lib/prawn/font.rb

@@ -14,6 +14,8 @@ require_relative "font_metric_cache"
 module Prawn
 
   class Document
+    # @group Stable API
+
     # Without arguments, this returns the currently selected font. Otherwise,
     # it sets the current font. When a block is used, the font is applied
     # transactionally and is rolled back when the block exits.
@@ -67,7 +69,10 @@ module Prawn
       @font
     end
 
+    # @method font_size(points=nil)
+    #
     # When called with no argument, returns the current font size.
+    #
     # When called with a single argument but no block, sets the current font
     # size.  When a block is used, the font size is applied transactionally and
     # is rolled back when the block exits.  You may still change the font size
@@ -98,59 +103,44 @@ module Prawn
       @font_size = size_before_yield
     end
 
-    # Sets the font directly, given an actual Font object
-    # and size.
-    #
-    def set_font(font, size=nil) # :nodoc:
-      @font = font
-      @font_size = size if size
+    # Sets the font size
+    def font_size=(size)
+      font_size(size)
     end
 
-    # Saves the current font, and then yields. When the block
-    # finishes, the original font is restored.
+    # Returns the width of the given string using the given font. If :size is not
+    # specified as one of the options, the string is measured using the current
+    # font size. You can also pass :kerning as an option to indicate whether
+    # kerning should be used when measuring the width (defaults to +false+).
     #
-    def save_font
-      @font ||= find_font("Helvetica")
-      original_font = @font
-      original_size = @font_size
-
-      yield
-    ensure
-      set_font(original_font, original_size) if original_font
-    end
-
-    # Looks up the given font using the given criteria. Once a font has been
-    # found by that matches the criteria, it will be cached to subsequent lookups
-    # for that font will return the same object.
+    # Note that the string _must_ be encoded properly for the font being used.
+    # For AFM fonts, this is WinAnsi. For TTF, make sure the font is encoded as
+    # UTF-8. You can use the Font#normalize_encoding method to make sure strings
+    # are in an encoding appropriate for the current font.
     #--
-    # Challenges involved: the name alone is not sufficient to uniquely identify
-    # a font (think dfont suitcases that can hold multiple different fonts in a
-    # single file). Thus, the :name key is included in the cache key.
+    # For the record, this method used to be a method of Font (and still delegates
+    # to width computations on Font). However, having the primary interface for
+    # calculating string widths exist on Font made it tricky to write extensions
+    # for Prawn in which widths are computed differently (e.g., taking formatting
+    # tags into account, or the like).
     #
-    # It is further complicated, however, since fonts in some formats (like the
-    # dfont suitcases) can be identified either by numeric index, OR by their
-    # name within the suitcase, and both should hash to the same font object
-    # (to avoid the font being embedded multiple times). This is not yet implemented,
-    # which means if someone selects a font both by name, and by index, the
-    # 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
+    # By putting width_of here, on Document itself, extensions may easily override
+    # it and redefine the width calculation behavior.
+    #++
+    def width_of(string, options={})
+      if p = options[:inline_format]
+        p = [] unless p.is_a?(Array)
 
-    # Hash of Font objects keyed by names
-    #
-    def font_registry #:nodoc:
-      @font_registry ||= {}
+        # Build up an Arranger with the entire string on one line, finalize it,
+        # and find its width.
+        arranger = Prawn::Text::Formatted::Arranger.new(self, options)
+        arranger.consumed = self.text_formatter.format(string, *p)
+        arranger.finalize_line
+
+        arranger.line_width
+      else
+        width_of_string(string, options)
+      end
     end
 
     # Hash that maps font family names to their styled individual font names.
@@ -197,39 +187,63 @@ module Prawn
         })
     end
 
-    # Returns the width of the given string using the given font. If :size is not
-    # specified as one of the options, the string is measured using the current
-    # font size. You can also pass :kerning as an option to indicate whether
-    # kerning should be used when measuring the width (defaults to +false+).
+    # @group Experimental API
+
+    # Sets the font directly, given an actual Font object
+    # and size.
     #
-    # Note that the string _must_ be encoded properly for the font being used.
-    # For AFM fonts, this is WinAnsi. For TTF, make sure the font is encoded as
-    # UTF-8. You can use the Font#normalize_encoding method to make sure strings
-    # are in an encoding appropriate for the current font.
-    #--
-    # For the record, this method used to be a method of Font (and still delegates
-    # to width computations on Font). However, having the primary interface for
-    # calculating string widths exist on Font made it tricky to write extensions
-    # for Prawn in which widths are computed differently (e.g., taking formatting
-    # tags into account, or the like).
+    def set_font(font, size=nil) # :nodoc:
+      @font = font
+      @font_size = size if size
+    end
+
+    # Saves the current font, and then yields. When the block
+    # finishes, the original font is restored.
     #
-    # By putting width_of here, on Document itself, extensions may easily override
-    # it and redefine the width calculation behavior.
-    #++
-    def width_of(string, options={})
-      if p = options[:inline_format]
-        p = [] unless p.is_a?(Array)
+    def save_font
+      @font ||= find_font("Helvetica")
+      original_font = @font
+      original_size = @font_size
 
-        # Build up an Arranger with the entire string on one line, finalize it,
-        # and find its width.
-        arranger = Prawn::Text::Formatted::Arranger.new(self, options)
-        arranger.consumed = self.text_formatter.format(string, *p)
-        arranger.finalize_line
+      yield
+    ensure
+      set_font(original_font, original_size) if original_font
+    end
 
-        arranger.line_width
-      else
-        width_of_string(string, options)
+    # Looks up the given font using the given criteria. Once a font has been
+    # found by that matches the criteria, it will be cached to subsequent lookups
+    # for that font will return the same object.
+    #--
+    # Challenges involved: the name alone is not sufficient to uniquely identify
+    # a font (think dfont suitcases that can hold multiple different fonts in a
+    # single file). Thus, the :name key is included in the cache key.
+    #
+    # It is further complicated, however, since fonts in some formats (like the
+    # dfont suitcases) can be identified either by numeric index, OR by their
+    # name within the suitcase, and both should hash to the same font object
+    # (to avoid the font being embedded multiple times). This is not yet implemented,
+    # which means if someone selects a font both by name, and by index, the
+    # font will be embedded twice. Since we do font subsetting, this double
+    # embedding won't be catastrophic, just annoying.
+    # ++
+    #
+    # @private
+    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:
+      @font_registry ||= {}
     end
 
     private

data/lib/prawn/font/afm.rb

@@ -10,6 +10,9 @@ require_relative '../../prawn/encoding'
 
 module Prawn
   class Font
+
+    # @private
+
     class AFM < Font
       BUILT_INS = %w[ Courier Helvetica Times-Roman Symbol ZapfDingbats
                       Courier-Bold Courier-Oblique Courier-BoldOblique

data/lib/prawn/font/dfont.rb

@@ -10,6 +10,7 @@ require_relative 'ttf'
 
 module Prawn
   class Font
+    # @private
     class DFont < TTF
 
       # Returns a list of the names of all named fonts in the given dfont file.

data/lib/prawn/font/ttf.rb

@@ -12,6 +12,8 @@ require 'ttfunk/subset_collection'
 
 module Prawn
   class Font
+
+    # @private
     class TTF < Font
       attr_reader :ttf, :subsets
 

data/lib/prawn/font_metric_cache.rb

@@ -11,7 +11,9 @@ module Prawn
 
   # Cache used internally by Prawn::Document instances to calculate the width
   # of various strings for layout purposes.
-  class FontMetricCache
+  #
+  # @private
+  class FontMetricCache 
 
     CacheEntry = Struct.new( :font, :options, :string )
 

data/lib/prawn/graphics.rb

@@ -33,6 +33,8 @@ module Prawn
     include Transformation
     include Patterns
 
+    # @group Stable API
+
     #######################################################################
     # Low level drawing operations must map the point to absolute coords! #
     #######################################################################
@@ -182,13 +184,6 @@ module Prawn
     #
     KAPPA = 4.0 * ((Math.sqrt(2) - 1.0) / 3.0)
 
-    # <b>DEPRECATED:</b> Please use <tt>circle</tt> instead.
-    def circle_at(point, options)
-      warn "[DEPRECATION] 'circle_at' is deprecated in favor of 'circle'. " +
-           "'circle_at' will be removed in release 1.1"
-      circle(point, options[:radius])
-    end
-
     # Draws a circle of radius <tt>radius</tt> with the centre-point at <tt>point</tt>
     # as a complete subpath. The drawing point will be moved to the
     # centre-point upon completion of the drawing the circle.
@@ -199,13 +194,6 @@ module Prawn
       ellipse(center, radius, radius)
     end
 
-    # <b>DEPRECATED:</b> Please use <tt>ellipse</tt> instead.
-    def ellipse_at(point, r1, r2=r1)
-      warn "[DEPRECATION] 'ellipse_at' is deprecated in favor of 'ellipse'. " +
-           "'ellipse_at' will be removed in release 1.1"
-      ellipse(point, r1, r2)
-    end
-
     # Draws an ellipse of +x+ radius <tt>r1</tt> and +y+ radius <tt>r2</tt>
     # with the centre-point at <tt>point</tt> as a complete subpath. The
     # drawing point will be moved to the centre-point upon completion of the

data/lib/prawn/graphics/cap_style.rb

@@ -9,6 +9,7 @@
 module Prawn
   module Graphics
     module CapStyle
+      # @group Stable API
 
       CAP_STYLES = { :butt => 0, :round => 1, :projecting_square => 2 }
 

data/lib/prawn/graphics/color.rb

@@ -9,6 +9,7 @@
 module Prawn
   module Graphics
     module Color
+      # @group Stable API
 
       # Sets or returns the fill color.
       #

data/lib/prawn/graphics/dash.rb

@@ -9,6 +9,7 @@
 module Prawn
   module Graphics
     module Dash
+      # @group Stable API
 
       # Sets the dash pattern for stroked lines and curves or return the
       # current dash pattern setting if +length+ is nil.
@@ -76,12 +77,12 @@ module Prawn
         current_dash_state != undashed_setting
       end
 
+      private
+
       def write_stroke_dash
         add_content dash_setting
       end
 
-      private
-
       def undashed_setting
         { :dash => nil, :space => nil, :phase => 0 }
       end

data/lib/prawn/graphics/join_style.rb

@@ -11,6 +11,8 @@ module Prawn
     module JoinStyle
       JOIN_STYLES = { :miter => 0, :round => 1, :bevel => 2 }
 
+      # @group Stable API
+
       # Sets the join style for stroked lines and curves
       #
       # style is one of :miter, :round, or :bevel

data/lib/prawn/graphics/patterns.rb

@@ -10,6 +10,7 @@
 module Prawn
   module Graphics
     module Patterns
+      # @group Stable API
 
       # Sets the fill gradient from color1 to color2.
       # old arguments: point, width, height, color1, color2, options = {}

data/lib/prawn/graphics/transformation.rb

@@ -10,6 +10,7 @@
 module Prawn
   module Graphics
     module Transformation
+      # @group Stable API
 
       # Rotate the user space.  If a block is not provided, then you must save
       # and restore the graphics state yourself.

data/lib/prawn/graphics/transparency.rb

@@ -30,6 +30,8 @@ module Prawn
     #
     module Transparency
 
+      # @group Stable API
+
       # 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

data/lib/prawn/image_handler.rb

@@ -1,4 +1,6 @@
 module Prawn
+  # @group Extension API
+  
   def self.image_handler
     @image_handler ||= ImageHandler.new
   end

data/lib/prawn/images.rb

@@ -11,6 +11,8 @@ require 'pathname'
 module Prawn
 
   module Images
+    # @group Stable API
+
     # Add the image at filename to the current page. Currently only
     # JPG and PNG files are supported. (Note that processing PNG
     # images with alpha channels can be processor and memory intensive.)
@@ -68,9 +70,11 @@ module Prawn
       info
     end
 
+
     # Builds an info object (Prawn::Images::*) and a PDF reference representing
     # the given image. Return a pair: [pdf_obj, info].
     #
+    # @private
     def build_image_object(file)
       io = verify_and_open_image(file)
       image_content = io.read
@@ -100,6 +104,7 @@ module Prawn
     # build_image_object), embed the image according to the <tt>options</tt>
     # given.
     #
+    # @private
     def embed_image(pdf_obj, info, options)
       # find where the image will be placed and how big it will be
       w,h = info.calc_image_dimensions(options)