prawn 2.4.0 → 2.5.0

data/lib/prawn/fonts/afm.rb

@@ -1,24 +1,31 @@
 # frozen_string_literal: true
 
-# Implements AFM font support for Prawn
-#
-# Copyright May 2008, Gregory Brown / James Healy.  All Rights Reserved.
-#
-# This is free software. Please see the LICENSE and COPYING files for details.
-
 require_relative '../encoding'
 
 module Prawn
   module Fonts
-    # @private
-
+    # AFM font. AFM stands for Adobe Font Metrics. It's not a complete font, it
+    # doesn't provide actual glyph outlines. It only contains glyph metrics to
+    # make text layout possible. AFM is used for PDF built-in fonts. Those
+    # fonts are supposed to be present on the target system making it possible
+    # to save a little bit of space by not embedding the fonts. A file that uses
+    # these fonts can not be read on a system that doesn't have these fonts
+    # installed.
+    #
+    # @note You shouldn't use this class directly.
     class AFM < Font
       class << self
+        # Prawn would warn you if you're using non-ASCII glyphs with AFM fonts
+        # as not all implementations provide those glyphs. This attribute
+        # suppresses that warning.
+        #
+        # @return [Boolean] (false)
         attr_accessor :hide_m17n_warning
       end
 
       self.hide_m17n_warning = false
 
+      # List of PDF built-in fonts.
       BUILT_INS = %w[
         Courier Helvetica Times-Roman Symbol ZapfDingbats
         Courier-Bold Courier-Oblique Courier-BoldOblique
@@ -26,10 +33,16 @@ module Prawn
         Helvetica-Bold Helvetica-Oblique Helvetica-BoldOblique
       ].freeze
 
+      # Does this font support Unicode?
+      #
+      # @return [false]
       def unicode?
         false
       end
 
+      # Paths to look for AFM files at.
+      #
+      # @return [Array<String>]
       def self.metrics_path
         @metrics_path ||=
           if ENV['METRICS']
@@ -39,19 +52,27 @@ module Prawn
               '.', '/usr/lib/afm',
               '/usr/local/lib/afm',
               '/usr/openwin/lib/fonts/afm',
-              "#{Prawn::DATADIR}/fonts"
+              "#{Prawn::DATADIR}/fonts",
             ]
           end
       end
 
-      attr_reader :attributes #:nodoc:
+      # @private
+      attr_reader :attributes
 
-      # parse each ATM font file once only
+      # Parsed AFM data cache.
+      #
+      # @return [SynchronizedCache]
       def self.font_data
         @font_data ||= SynchronizedCache.new
       end
 
-      def initialize(document, name, options = {}) #:nodoc:
+      # @param document [Prawn::Document]
+      # @param name [String]
+      # @param options [Hash]
+      # @option options :family [String]
+      # @option options :style [Symbol]
+      def initialize(document, name, options = {})
         name ||= options[:family]
         unless BUILT_INS.include?(name)
           raise Prawn::Errors::UnknownFont,
@@ -62,7 +83,7 @@ module Prawn
 
         file_name = @name.dup
         file_name << '.afm' unless /\.afm$/.match?(file_name)
-        file_name = file_name[0] == '/' ? file_name : find_font(file_name)
+        file_name = find_font(file_name) unless file_name[0] == '/'
 
         font_data = self.class.font_data[file_name] ||= parse_afm(file_name)
         @glyph_widths = font_data[:glyph_widths]
@@ -72,19 +93,27 @@ module Prawn
         @kern_pair_table = font_data[:kern_pair_table]
         @attributes = font_data[:attributes]
 
-        @ascender = @attributes['ascender'].to_i
-        @descender = @attributes['descender'].to_i
+        @ascender = Integer(@attributes.fetch('ascender', '0'), 10)
+        @descender = Integer(@attributes.fetch('descender', '0'), 10)
         @line_gap = Float(bbox[3] - bbox[1]) - (@ascender - @descender)
       end
 
-      # The font bbox, as an array of integers
+      # The font bbox.
       #
+      # @return [Array(Number, Number, Number, Number)]
       def bbox
         @bbox ||= @attributes['fontbbox'].split(/\s+/).map { |e| Integer(e) }
       end
 
-      # NOTE: String *must* be encoded as WinAnsi
-      def compute_width_of(string, options = {}) #:nodoc:
+      # Compute width of a string at the specified size, optionally with kerning
+      # applied.
+      #
+      # @param string [String] *must* be encoded as WinAnsi
+      # @param options [Hash{Symbol => any}]
+      # @option options :size [Number]
+      # @option options :kerning [Boolean] (false)
+      # @return [Number]
+      def compute_width_of(string, options = {})
         scale = (options[:size] || size) / 1000.0
 
         if options[:kerning]
@@ -96,18 +125,19 @@ module Prawn
         end
       end
 
-      # Returns true if the font has kerning data, false otherwise
+      # Does this font contain kerning data.
       #
-      # rubocop: disable Naming/PredicateName
-      def has_kerning_data?
+      # @return [Boolean]
+      def has_kerning_data? # rubocop: disable Naming/PredicateName
         @kern_pairs.any?
       end
-      # rubocop: enable Naming/PredicateName
 
-      # built-in fonts only work with winansi encoding, so translate the
+      # 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.
       #
+      # @param text [String]
+      # @return [String]
       def normalize_encoding(text)
         text.encode('windows-1252')
       rescue ::Encoding::InvalidByteSequenceError,
@@ -115,17 +145,23 @@ module Prawn
 
         raise Prawn::Errors::IncompatibleStringEncoding,
           "Your document includes text that's not compatible with the " \
-          "Windows-1252 character set.\n" \
-          'If you need full UTF-8 support, use external fonts instead of ' \
-          "PDF's built-in fonts.\n"
+            "Windows-1252 character set.\n" \
+            'If you need full UTF-8 support, use external fonts instead of ' \
+            "PDF's built-in fonts.\n"
       end
 
+      # Encode text to UTF-8.
+      #
+      # @param text [String]
+      # @return [String]
       def to_utf8(text)
         text.encode('UTF-8')
       end
 
-      # Returns the number of characters in +str+ (a WinAnsi-encoded string).
+      # Returns the number of characters in `str` (a WinAnsi-encoded string).
       #
+      # @param str [String]
+      # @return [Integer]
       def character_count(str)
         str.length
       end
@@ -137,15 +173,23 @@ module Prawn
       # is either a string or an array (for kerned text).
       #
       # For Adobe fonts, there is only ever a single subset, so
-      # the first element of the array is "0", and the second is
+      # the first element of the array is `0`, and the second is
       # the string itself (or an array, if kerning is performed).
       #
-      # The +text+ parameter must be in WinAnsi encoding (cp1252).
+      # The `text` argument must be in WinAnsi encoding (cp1252).
       #
+      # @param text [String]
+      # @param options [Hash{Symbol => any}]
+      # @option options :kerning [Boolean]
+      # @return [Array<Array(0, (String, Array)>]
       def encode_text(text, options = {})
         [[0, options[:kerning] ? kern(text) : text]]
       end
 
+      # Does this font has a glyph for the character?
+      #
+      # @param char [String]
+      # @return [Boolean]
       def glyph_present?(char)
         !normalize_encoding(char).nil?
       rescue Prawn::Errors::IncompatibleStringEncoding
@@ -158,7 +202,7 @@ module Prawn
         font_dict = {
           Type: :Font,
           Subtype: :Type1,
-          BaseFont: name.to_sym
+          BaseFont: name.to_sym,
         }
 
         # Symbolic AFM fonts (Symbol, ZapfDingbats) have their own encodings
@@ -172,7 +216,7 @@ module Prawn
       end
 
       def find_font(file)
-        self.class.metrics_path.find { |f| File.exist? "#{f}/#{file}" } +
+        self.class.metrics_path.find { |f| File.exist?("#{f}/#{file}") } +
           "/#{file}"
       rescue NoMethodError
         raise Prawn::Errors::UnknownFont,
@@ -185,14 +229,14 @@ module Prawn
           glyph_widths: {},
           bounding_boxes: {},
           kern_pairs: {},
-          attributes: {}
+          attributes: {},
         }
         section = []
 
         File.foreach(file_name) do |line|
           case line
           when /^Start(\w+)/
-            section.push Regexp.last_match(1)
+            section.push(Regexp.last_match(1))
             next
           when /^End(\w+)/
             section.pop
@@ -204,13 +248,13 @@ module Prawn
             next unless /^CH?\s/.match?(line)
 
             name = line[/\bN\s+(\.?\w+)\s*;/, 1]
-            data[:glyph_widths][name] = line[/\bWX\s+(\d+)\s*;/, 1].to_i
+            data[:glyph_widths][name] = Integer(line[/\bWX\s+(\d+)\s*;/, 1], 10)
             data[:bounding_boxes][name] = line[/\bB\s+([^;]+);/, 1].to_s.rstrip
           when %w[FontMetrics KernData KernPairs]
             next unless line =~ /^KPX\s+(\.?\w+)\s+(\.?\w+)\s+(-?\d+)/
 
             data[:kern_pairs][[Regexp.last_match(1), Regexp.last_match(2)]] =
-              Regexp.last_match(3).to_i
+              Integer(Regexp.last_match(3), 10)
           when %w[FontMetrics KernData TrackKern],
             %w[FontMetrics Composites]
             next
@@ -222,15 +266,11 @@ module Prawn
         # process data parsed from AFM file to build tables which
         #   will be used when measuring and kerning text
         data[:glyph_table] =
-          (0..255).map do |i|
-            data[:glyph_widths][Encoding::WinAnsi::CHARACTERS[i]].to_i
-          end
+          (0..255).map { |i|
+            data[:glyph_widths].fetch(Encoding::WinAnsi::CHARACTERS[i], 0)
+          }
 
-        character_hash = Hash[
-          Encoding::WinAnsi::CHARACTERS.zip(
-            (0..Encoding::WinAnsi::CHARACTERS.size).to_a
-          )
-        ]
+        character_hash = Encoding::WinAnsi::CHARACTERS.zip((0..Encoding::WinAnsi::CHARACTERS.size).to_a).to_h
         data[:kern_pair_table] =
           data[:kern_pairs].each_with_object({}) do |p, h|
             h[p[0].map { |n| character_hash[n] }] = p[1]
@@ -254,7 +294,7 @@ module Prawn
       end
 
       # converts a string into an array with spacing offsets
-      # bewteen characters that need to be kerned
+      # between characters that need to be kerned
       #
       # String *must* be encoded as WinAnsi
       #
@@ -273,7 +313,7 @@ module Prawn
         end
 
         kerned.map do |e|
-          e = e.is_a?(Array) ? e.pack('C*') : e
+          e = e.pack('C*') if e.is_a?(Array)
           if e.respond_to?(:force_encoding)
             e.force_encoding(::Encoding::Windows_1252)
           else

data/lib/prawn/fonts/dfont.rb

@@ -4,7 +4,9 @@ require_relative 'ttf'
 
 module Prawn
   module Fonts
-    # @private
+    # DFONT font. DFONT is a bunch of TrueType fonts in a single file.
+    #
+    # @note You shouldn't use this class directly.
     class DFont < TTF
       # Returns a list of the names of all named fonts in the given dfont file.
       # Note that fonts are not required to be named in a dfont file, so the
@@ -12,6 +14,8 @@ module Prawn
       # the list is returned in no particular order, so the first font in the
       # list is not necessarily the font at index 0 in the file.
       #
+      # @param file [String]
+      # @return [Array<String>]
       def self.named_fonts(file)
         TTFunk::ResourceFile.open(file) do |f|
           return f.resources_for('sfnt')
@@ -20,6 +24,8 @@ module Prawn
 
       # Returns the number of fonts contained in the dfont file.
       #
+      # @param file [String]
+      # @return [Integer]
       def self.font_count(file)
         TTFunk::ResourceFile.open(file) do |f|
           return f.map['sfnt'][:list].length

data/lib/prawn/fonts/otf.rb

@@ -4,7 +4,10 @@ require_relative 'ttf'
 
 module Prawn
   module Fonts
-    # @private
+    # OpenType font. This class is used mostly to distinguish OTF from TTF.
+    # All functionality is in the {Fonts::TTF} class.
+    #
+    # @note You shouldn't use this class directly.
     class OTF < TTF
     end
   end

data/lib/prawn/fonts/to_unicode_cmap.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Prawn
+  module Fonts
+    # This class generates ToUnicode CMap for embedde TrueType/OpenType fonts.
+    # It's a separate format and is somewhat complicated so it has its own
+    # place.
+    #
+    # @private
+    class ToUnicodeCMap
+      # mapping is expected to be a hash with keys being character codes (in
+      # broad sense, as used in the showing operation strings) and values being
+      # Unicode code points.
+      def initialize(mapping, code_space_size = nil)
+        @mapping = mapping
+        @code_space_size = code_space_size
+      end
+
+      # Generate CMap.
+      #
+      # @return [String]
+      def generate
+        chunks = []
+
+        # Header
+        chunks << <<~HEADER.chomp
+          /CIDInit /ProcSet findresource begin
+          12 dict begin
+          begincmap
+          /CIDSystemInfo 3 dict dup begin
+            /Registry (Adobe) def
+            /Ordering (UCS) def
+            /Supplement 0 def
+          end def
+          /CMapName /Adobe-Identity-UCS def
+          /CMapType 2 def
+        HEADER
+
+        max_glyph_index = mapping.keys.max
+        # Range
+        code_space_size = (max_glyph_index.bit_length / 8.0).ceil
+
+        used_code_space_size = @code_space_size || code_space_size
+
+        # In CMap codespaces are not sequentional, they're ranges in
+        # a multi-dimentional space. Each byte is considered separately. So we
+        # have to maximally extend the lower bytes in order to allow for
+        # continuos mapping.
+        # We only keep the highest byte because usually it's lower than
+        # maximally allowed and we don't want to cover that unused space.
+        code_space_max = max_glyph_index | ('ff' * (code_space_size - 1)).to_i(16)
+
+        chunks << '1 begincodespacerange'
+        chunks << format("<%0#{used_code_space_size * 2}X><%0#{used_code_space_size * 2}X>", 0, code_space_max)
+        chunks << 'endcodespacerange'
+
+        # Mapping
+        all_spans = mapping_spans(mapping.reject { |gid, cid| gid.zero? || (0xd800..0xdfff).cover?(cid) })
+
+        short_spans, long_spans = all_spans.partition { |span| span[0] == :short }
+
+        long_spans
+          .each_slice(100) do |spans|
+            chunks << "#{spans.length} beginbfrange"
+
+            spans.each do |type, span|
+              # rubocop: disable Lint/FormatParameterMismatch # false positive
+              case type
+              when :fully_sorted
+                chunks << format(
+                  "<%0#{code_space_size * 2}X><%0#{code_space_size * 2}X><%s>",
+                  span.first[0],
+                  span.last[0],
+                  span.first[1].chr(::Encoding::UTF_16BE).unpack1('H*'),
+                )
+              when :index_sorted
+                chunks << format(
+                  "<%0#{code_space_size * 2}X><%0#{code_space_size * 2}X>[%s]",
+                  span.first[0],
+                  span.last[0],
+                  span.map { |_, cid| "<#{cid.chr(::Encoding::UTF_16BE).unpack1('H*')}>" }.join(''),
+                )
+              end
+              # rubocop: enable Lint/FormatParameterMismatch
+            end
+
+            chunks << 'endbfrange'
+          end
+
+        short_spans
+          .map { |_type, slice| slice.flatten(1) }
+          .each_slice(100) do |mapping|
+            chunks << "#{mapping.length} beginbfchar"
+            chunks.concat(
+              mapping.map { |(gid, cid)|
+                # rubocop: disable Lint/FormatParameterMismatch # false positive
+                format(
+                  "<%0#{code_space_size * 2}X><%s>",
+                  gid,
+                  cid.chr(::Encoding::UTF_16BE).unpack1('H*'),
+                )
+                # rubocop: enable Lint/FormatParameterMismatch
+              },
+            )
+            chunks << 'endbfchar'
+          end
+
+        # Footer
+        chunks << <<~FOOTER.chomp
+          endcmap
+          CMapName currentdict /CMap defineresource pop
+          end
+          end
+        FOOTER
+
+        chunks.join("\n")
+      end
+
+      private
+
+      attr_reader :mapping
+
+      attr_reader :cmap
+      attr_reader :code_space_size
+      attr_reader :code_space_max
+
+      def mapping_spans(mapping)
+        mapping
+          .sort
+          .slice_when { |a, b| (b[0] - a[0]) != 1 } # Slice at key discontinuity
+          .flat_map { |slice|
+            if slice.length == 1
+              [[:short, slice]]
+            else
+              continuous_slices, discontinuous_slices =
+                slice
+                  .slice_when { |a, b| b[1] - a[1] != 1 } # Slice at value discontinuity
+                  .partition { |subslice| subslice.length > 1 }
+
+              discontinuous_slices
+                .flatten(1) # Join together
+                .slice_when { |a, b| (b[0] - a[0]) != 1 } # Slice at key discontinuity, again
+                .map { |span| span.length > 1 ? [:index_sorted, span] : [:short, slice] } +
+                continuous_slices.map { |span| [:fully_sorted, span] }
+            end
+          } # rubocop: disable Style/MultilineBlockChain
+          .sort_by { |span| span[1][0][0] } # Sort span start key
+      end
+    end
+  end
+end

data/lib/prawn/fonts/ttc.rb

@@ -4,11 +4,16 @@ require_relative 'ttf'
 
 module Prawn
   module Fonts
-    # @private
+    # TrueType Collection font. It's an SFNT-based format that contains a bunch
+    # of TrueType fonts in a single file.
+    #
+    # @note You shouldn't use this class directly.
     class TTC < TTF
       # Returns a list of the names of all named fonts in the given ttc file.
       # They are returned in order of their appearance in the file.
       #
+      # @param file [String]
+      # @return [Array<String>]
       def self.font_names(file)
         TTFunk::Collection.open(file) do |ttc|
           ttc.map { |font| font.name.font_name.first }
@@ -20,7 +25,7 @@ module Prawn
       def read_ttf_file
         TTFunk::File.from_ttc(
           @name,
-          font_option_to_index(@name, @options[:font])
+          font_option_to_index(@name, @options[:font]),
         )
       end