piglop-prawn 0.10.2.1

data/lib/prawn/font.rb

@@ -0,0 +1,342 @@
+# encoding: utf-8
+#
+# font.rb : The Prawn font class
+#
+# Copyright May 2008, Gregory Brown / James Healy. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+#
+require "prawn/font/afm"
+require "prawn/font/ttf"
+require "prawn/font/dfont"
+
+module Prawn
+
+  class Document
+    # 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.
+    #
+    #   Prawn::Document.generate("font.pdf") do
+    #     text "Default font is Helvetica"
+    #
+    #     font "Times-Roman"
+    #     text "Now using Times-Roman"
+    #
+    #     font("Chalkboard.ttf") do
+    #       text "Using TTF font from file Chalkboard.ttf"
+    #       font "Courier", :style => :bold
+    #       text "You see this in bold Courier"
+    #     end
+    #
+    #     text "Times-Roman, again"
+    #   end
+    #
+    # The :name parameter must be a string. It can be one of the 14 built-in
+    # fonts supported by PDF, or the location of a TTF file. The Font::AFM::BUILT_INS
+    # array specifies the valid built in font values.
+    #
+    # If a ttf font is specified, the glyphs necessary to render your document
+    # will be embedded in the rendered PDF. This should be your preferred option
+    # in most cases. It will increase the size of the resulting file, but also 
+    # make it more portable.
+    #
+    # The options parameter is an optional hash providing size and style. To use
+    # the :style option you need to map those font styles to their respective font files.
+    # See font_families for more information.
+    #
+    def font(name=nil, options={})
+      return((defined?(@font) && @font) || font("Helvetica")) if name.nil?
+
+      if state.pages.empty? && !state.page.in_stamp_stream?
+        raise Prawn::Errors::NotOnPage 
+      end
+      
+      new_font = find_font(name, options)
+
+      if block_given?
+        save_font do
+          set_font(new_font, options[:size])
+          yield
+        end
+      else
+        set_font(new_font, options[:size])
+      end
+
+      @font
+    end
+
+    # 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
+    # within a transactional block for individual text segments, or nested calls
+    # to font_size.
+    #
+    #   Prawn::Document.generate("font_size.pdf") do
+    #     font_size 16
+    #     text "At size 16"
+    #
+    #     font_size(10) do
+    #       text "At size 10"
+    #       text "At size 6", :size => 6
+    #       text "At size 10"
+    #     end
+    #
+    #     text "At size 16"
+    #   end
+    #
+    # When called without an argument, this method returns the current font
+    # size.
+    #
+    def font_size(points=nil)
+      return @font_size unless points
+      size_before_yield = @font_size
+      @font_size = points
+      block_given? ? yield : return
+      @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
+    end
+
+    # Saves the current font, and then yields. When the block
+    # finishes, the original font is restored.
+    #
+    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.
+    #--
+    # 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.
+    # ++
+    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
+
+    # Hash that maps font family names to their styled individual font names.
+    #
+    # To add support for another font family, append to this hash, e.g:
+    #
+    #   pdf.font_families.update(
+    #    "MyTrueTypeFamily" => { :bold        => "foo-bold.ttf",
+    #                            :italic      => "foo-italic.ttf",
+    #                            :bold_italic => "foo-bold-italic.ttf",
+    #                            :normal      => "foo.ttf" })
+    #
+    # This will then allow you to use the fonts like so:
+    #
+    #   pdf.font("MyTrueTypeFamily", :style => :bold)
+    #   pdf.text "Some bold text"
+    #   pdf.font("MyTrueTypeFamily")
+    #   pdf.text "Some normal text"
+    #
+    # This assumes that you have appropriate TTF fonts for each style you
+    # wish to support.
+    #
+    # By default the styles :bold, :italic, :bold_italic, and :normal are
+    # defined for fonts "Courier", "Times-Roman" and "Helvetica".
+    #
+    # You probably want to provide those four styles, but are free to define
+    # custom ones, like :thin, and use them in font calls.
+    #
+    def font_families
+      @font_families ||= Hash.new { |h,k| h[k] = {} }.merge!(
+        { "Courier"     => { :bold        => "Courier-Bold",
+                             :italic      => "Courier-Oblique",
+                             :bold_italic => "Courier-BoldOblique",
+                             :normal      => "Courier" },
+
+          "Times-Roman" => { :bold         => "Times-Bold",
+                             :italic       => "Times-Italic",
+                             :bold_italic  => "Times-BoldItalic",
+                             :normal       => "Times-Roman" },
+
+          "Helvetica"   => { :bold         => "Helvetica-Bold",
+                             :italic       => "Helvetica-Oblique",
+                             :bold_italic  => "Helvetica-BoldOblique",
+                             :normal       => "Helvetica" }
+        })
+    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+).
+    #
+    # 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).
+    #
+    # By putting width_of here, on Document itself, extensions may easily override
+    # it and redefine the width calculation behavior.
+    #++
+    def width_of(string, options={})
+      font.compute_width_of(string, options)
+    end
+  end
+
+  # Provides font information and helper functions.
+  #
+  class Font
+
+    # The current font name
+    attr_reader :name
+
+    # The current font family
+    attr_reader :family
+
+    # 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)
+      when /\.dfont$/ then DFont.new(document, name, options)
+      when /\.afm$/   then AFM.new(document, name, options)
+      else                 AFM.new(document, name, options)
+      end
+    end
+
+    def initialize(document,name,options={}) #:nodoc:
+      @document   = document
+      @name       = name
+      @options    = options
+
+      @family     = options[:family]
+
+      @identifier = :"F#{@document.font_registry.size + 1}"
+
+      @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
+    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}".to_sym
+    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)
+    # version, see normalize_encoding!.
+    #
+    def normalize_encoding(string)
+      raise NotImplementedError, "subclasses of Prawn::Font must implement #normalize_encoding"
+    end
+
+    # 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
+    end
+
+    # Gets height of current font in PDF points at current font size
+    #
+    def height
+      height_at(size)
+    end
+
+    # Registers the given subset of the current font with the current PDF
+    # page. This is safe to call multiple times for a given font and subset,
+    # as it will only add the font the first time it is called.
+    #
+    def add_to_current_page(subset)
+      @references[subset] ||= register(subset)
+      @document.state.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
+      @document.font_size
+    end
+
+  end
+
+end

data/lib/prawn/graphics/cap_style.rb

@@ -0,0 +1,38 @@
+# encoding: utf-8   
+
+# cap_style.rb : Implements stroke cap styling
+#
+# Contributed by Daniel Nelson. October, 2009
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+#
+module Prawn
+  module Graphics
+    module CapStyle
+
+      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?
+
+        @cap_style = style
+
+        write_stroke_cap_style
+      end
+      
+      alias_method :cap_style=, :cap_style
+
+      private
+
+      def write_stroke_cap_style
+        add_content "#{CAP_STYLES[@cap_style]} J"
+      end
+    end
+  end
+end

data/lib/prawn/graphics/color.rb

@@ -0,0 +1,205 @@
+# encoding: utf-8
+
+# color.rb : Implements color handling
+#
+# Copyright June 2008, Gregory Brown.  All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+module Prawn
+  module Graphics
+    module Color
+
+      # Sets or returns the fill color.
+      #
+      # When called with no argument, it returns the current fill 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)
+        set_fill_color
+      end
+
+      alias_method :fill_color=, :fill_color
+
+      # Sets or returns the line stroking color.
+      #
+      # When called with no argument, it returns the current stroking 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)
+        return @stroke_color if color.empty?
+        @stroke_color = process_color(*color)
+        set_stroke_color
+      end
+
+      alias_method :stroke_color=, :stroke_color
+
+      # Provides the following shortcuts:
+      #
+      #    stroke_some_method(*args) #=> some_method(*args); stroke
+      #    fill_some_method(*args) #=> some_method(*args); fill
+      #    fill_and_stroke_some_method(*args) #=> some_method(*args); fill_and_stroke
+      #
+      def method_missing(id,*args,&block)
+        case(id.to_s)
+        when /^fill_and_stroke_(.*)/
+          send($1,*args,&block); fill_and_stroke
+        when /^stroke_(.*)/
+          send($1,*args,&block); stroke
+        when /^fill_(.*)/
+          send($1,*args,&block); fill
+        else
+          super
+        end
+      end
+
+      module_function
+
+      # Converts RGB value array to hex string suitable for use with fill_color
+      # and stroke_color
+      #
+      #   >> Prawn::Graphics::Color.rgb2hex([255,120,8])
+      #   => "ff7808"
+      #
+      def rgb2hex(rgb)
+        rgb.map { |e| "%02x" % e }.join
+      end
+
+      # Converts hex string into RGB value array:
+      #
+      #  >> Prawn::Graphics::Color.hex2rgb("ff7808")
+      #  => [255, 120, 8]
+      #
+      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
+
+      private
+
+      def process_color(*color)
+        case(color.size)
+        when 1
+          color[0]
+        when 4
+          color
+        else
+          raise ArgumentError, 'wrong number of arguments supplied'
+        end
+      end
+
+      def color_type(color)
+        case color
+        when String
+          :RGB
+        when Array
+          :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
+
+      def color_to_s(color)
+        normalize_color(color).map { |c| '%.3f' % c }.join(' ')
+      end
+
+      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
+

data/lib/prawn/graphics/dash.rb

@@ -0,0 +1,71 @@
+# encoding: utf-8   
+
+# dash.rb : Implements stroke dashing
+#
+# Contributed by Daniel Nelson. October, 2009
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+#
+module Prawn
+  module Graphics
+    module Dash
+
+      # Sets the dash pattern for stroked lines and curves
+      #
+      #   length is the length of the dash. If options is not present,
+      #   or options[:space] is nil, then length is also the length of
+      #   the space between dashes
+      #
+      #   options may contain :space and :phase
+      #      :space is the space between the dashes
+      #      :phase is where in the cycle to begin dashing. For
+      #             example, a phase of 0 starts at the beginning of
+      #             the dash; whereas, if the phase is equal to the
+      #             length of the dash, then stroking will begin at
+      #             the beginning of the space. Default is 0
+      #
+      #   integers or floats may be used for length and the options
+      #
+      #   dash units are in PDF points ( 1/72 in )
+      #   
+      def dash(length=nil, options={})
+        return @dash || undash_hash if length.nil?
+
+        @dash = { :dash  => length, 
+                  :space => options[:space] || length, 
+                  :phase => options[:phase] || 0 }
+
+        write_stroke_dash
+      end
+      
+      alias_method :dash=, :dash
+
+      # Stops dashing, restoring solid stroked lines and curves
+      #
+      def undash
+        @dash = undash_hash
+        write_stroke_dash
+      end
+      
+      # Returns when stroke is dashed, false otherwise
+      #
+      def dashed?
+        dash != undash_hash
+      end
+
+      private
+
+      def undash_hash
+        { :dash => nil, :space => nil, :phase => 0 }
+      end
+
+      def write_stroke_dash
+        if @dash[:dash].nil?
+          add_content "[] 0 d"
+          return
+        end
+        add_content "[#{@dash[:dash]} #{@dash[:space]}] #{@dash[:phase]} d"
+      end     
+    end
+  end
+end

data/lib/prawn/graphics/join_style.rb

@@ -0,0 +1,38 @@
+# encoding: utf-8   
+
+# join_style.rb : Implements stroke join styling
+#
+# Contributed by Daniel Nelson. October, 2009
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+#
+module Prawn
+  module Graphics
+    module JoinStyle
+      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?
+
+        @join_style = style
+
+        write_stroke_join_style
+      end
+      
+      alias_method :join_style=, :join_style
+
+      private
+
+      def write_stroke_join_style
+        add_content "#{JOIN_STYLES[@join_style]} j"
+      end
+    end
+  end
+end