ttfunk 1.7.0 → 1.8.0

data/lib/ttfunk/subset_collection.rb

@@ -3,26 +3,48 @@
 require_relative 'subset'
 
 module TTFunk
+  # Subset collection.
+  #
+  # For many use cases a font subset can be efficiently encoded using MacRoman
+  # encoding. However, for full font coverage and characters that are not in
+  # MacRoman encoding an additional Unicode subset is used. There can be as many
+  # as needed Unicode subsets to fully cover glyphs provided by the original
+  # font. Ther resulting set of subsets all use 8-bit encoding helping to
+  # efficiently encode text in Prawn.
   class SubsetCollection
+    # @param original [TTFunk::File]
     def initialize(original)
       @original = original
       @subsets = [Subset.for(@original, :mac_roman)]
     end
 
+    # Get subset by index.
+    #
+    # @param subset [Integer]
+    # @return [TTFunk::Subset::Unicode, TTFunk::Subset::Unicode8Bit,
+    #   TTFunk::Subset::MacRoman, TTFunk::Subset::Windows1252]
     def [](subset)
       @subsets[subset]
     end
 
-    # +characters+ should be an array of UTF-16 characters
+    # Add chracters to appropiate subsets.
+    #
+    # @param characters [Array<Integer>] should be an array of UTF-16 code
+    #   points
+    # @return [void]
     def use(characters)
       characters.each do |char|
         covered = false
-        @subsets.each_with_index do |subset, _i|
-          next unless subset.covers?(char)
-
-          subset.use(char)
-          covered = true
-          break
+        i = 0
+        length = @subsets.length
+        while i < length
+          subset = @subsets[i]
+          if subset.covers?(char)
+            subset.use(char)
+            covered = true
+            break
+          end
+          i += 1
         end
 
         unless covered
@@ -32,13 +54,16 @@ module TTFunk
       end
     end
 
-    # +characters+ should be an array of UTF-16 characters. Returns
-    # an array of subset chunks, where each chunk is another array of
-    # two elements. The first element is the subset number, and the
-    # second element is the string of characters to render with that
-    # font subset. The strings will be encoded for their subset font,
-    # and so may not look (in the raw) like what was passed in, but
-    # they will render correctly with the indicated subset font.
+    # Encode characters into subset-character pairs.
+    #
+    # @param characters [Array<Integer>] should be an array of UTF-16 code
+    #   points
+    # @return [Array<Array(Integer, String)>] subset chunks, where each chunk
+    #   is another array of two elements. The first element is the subset
+    #   number, and the second element is the string of characters to render
+    #   with that font subset. The strings will be encoded for their subset
+    #   font, and so may not look (in the raw) like what was passed in, but they
+    #   will render correctly with the corresponding subset font.
     def encode(characters)
       return [] if characters.empty?
 

data/lib/ttfunk/sum.rb

@@ -1,18 +1,31 @@
 # frozen_string_literal: true
 
 module TTFunk
+  # Sum aggreaget. Is sums all pushed values.
   class Sum < Aggregate
+    # Value
+    #
+    # @return [#+]
     attr_reader :value
 
+    # @param init_value [#+] initial value
     def initialize(init_value = 0)
       super()
       @value = init_value
     end
 
+    # Push a value. It will be added to the current value.
+    #
+    # @param operand [any]
+    # @return [void]
     def <<(operand)
       @value += coerce(operand)
     end
 
+    # Get the stored value or default.
+    #
+    # @param _default [any] Unused. Here for API compatibility.
+    # @return [any]
     def value_or(_default)
       # value should always be non-nil
       value

data/lib/ttfunk/table/cff/charset.rb

@@ -3,25 +3,47 @@
 module TTFunk
   class Table
     class Cff < TTFunk::Table
+      # CFF Charset
       class Charset < TTFunk::SubTable
         include Enumerable
 
+        # First glyph string. This is an implicit glyph present in all charsets.
         FIRST_GLYPH_STRING = '.notdef'
+
+        # Format 0.
         ARRAY_FORMAT = 0
+
+        # Format 1.
         RANGE_FORMAT_8 = 1
+
+        # Format 2.
         RANGE_FORMAT_16 = 2
 
+        # Predefined ISOAdobe charset ID.
         ISO_ADOBE_CHARSET_ID = 0
+
+        # Predefined Expert charset ID.
         EXPERT_CHARSET_ID = 1
+
+        # Predefined Expert Subset charset ID.
         EXPERT_SUBSET_CHARSET_ID = 2
 
+        # Default charset ID.
         DEFAULT_CHARSET_ID = ISO_ADOBE_CHARSET_ID
 
         class << self
+          # Standard strings defined in the spec that do not need to be defined
+          # in the CFF.
+          #
+          # @return [TTFunk::OneBasedArray<String>]
           def standard_strings
             Charsets::STANDARD_STRINGS
           end
 
+          # Strings for charset ID.
+          #
+          # @param charset_id [Integer]
+          # @return [TTFunk::OneBasedArray<String>]
           def strings_for_charset_id(charset_id)
             case charset_id
             when ISO_ADOBE_CHARSET_ID
@@ -34,9 +56,39 @@ module TTFunk
           end
         end
 
-        attr_reader :entries, :length
-        attr_reader :top_dict, :format, :count, :offset_or_id
-
+        # Encoded entries.
+        # @return [TTFunk::OneBasedArray<Integer>, Array<Range<Integer>>]
+        attr_reader :entries
+
+        # Length of encoded charset subtable.
+        # @return [Integer]
+        attr_reader :length
+
+        # Top dict.
+        # @return [TTFunk::Table::Cff::TopDict]
+        attr_reader :top_dict
+
+        # Encodign format.
+        # @return [Integer]
+        attr_reader :format
+
+        # Number of encoded items.
+        # @return [Integer]
+        attr_reader :items_count
+
+        # Offset or charset ID.
+        # @return [Integer]
+        attr_reader :offset_or_id
+
+        # @overload initialize(top_dict, file, offset = nil, length = nil)
+        #   @param top_dict [TTFunk::Table:Cff::TopDict]
+        #   @param file [TTFunk::File]
+        #   @param offset [Integer]
+        #   @param length [Integer]
+        # @overload initialize(top_dict, file, charset_id)
+        #   @param top_dict [TTFunk::Table:Cff::TopDict]
+        #   @param file [TTFunk::File]
+        #   @param charset_id [Integer] 0, 1, or 2
         def initialize(top_dict, file, offset_or_id = nil, length = nil)
           @top_dict = top_dict
           @offset_or_id = offset_or_id || DEFAULT_CHARSET_ID
@@ -44,23 +96,37 @@ module TTFunk
           if offset
             super(file, offset, length)
           else
-            @count = self.class.strings_for_charset_id(offset_or_id).size
+            @items_count = self.class.strings_for_charset_id(offset_or_id).size
           end
         end
 
+        # Iterate over character names.
+        #
+        # @overload each()
+        #   @yieldparam name [String]
+        #   @return [void]
+        # @overload each()
+        #   @return [Enumerator]
         def each
           return to_enum(__method__) unless block_given?
 
           # +1 adjusts for the implicit .notdef glyph
-          (count + 1).times { |i| yield self[i] }
+          (items_count + 1).times { |i| yield(self[i]) }
         end
 
+        # Get character name for glyph index.
+        #
+        # @param glyph_id [Integer]
+        # @return [String, nil]
         def [](glyph_id)
           return FIRST_GLYPH_STRING if glyph_id.zero?
 
           find_string(sid_for(glyph_id))
         end
 
+        # Charset offset in the file.
+        #
+        # @return [Integer, nil]
         def offset
           # Numbers from 0..2 mean charset IDs instead of offsets. IDs are
           # basically pre-defined sets of characters.
@@ -73,13 +139,25 @@ module TTFunk
           end
         end
 
-        # mapping is new -> old glyph ids
-        def encode(mapping)
+        # Encode charset.
+        #
+        # @param charmap [Hash{Integer => Hash}] keys are the charac codes,
+        #   values are hashes:
+        #   * `:old` (<tt>Integer</tt>) - glyph ID in the original font.
+        #   * `:new` (<tt>Integer</tt>) - glyph ID in the subset font.
+        # @return [String]
+        def encode(charmap)
           # no offset means no charset was specified (i.e. we're supposed to
           # use a predefined charset) so there's nothing to encode
           return '' unless offset
 
-          sids = mapping.keys.sort.map { |new_gid| sid_for(mapping[new_gid]) }
+          sids =
+            charmap
+              .values
+              .reject { |mapping| mapping[:new].zero? }
+              .sort_by { |mapping| mapping[:new] }
+              .map { |mapping| sid_for(mapping[:old]) }
+
           ranges = TTFunk::BinUtils.rangify(sids)
           range_max = ranges.map(&:last).max
 
@@ -138,7 +216,7 @@ module TTFunk
 
             idx = sid - 390
 
-            if idx < file.cff.string_index.count
+            if idx < file.cff.string_index.items_count
               file.cff.string_index[idx]
             end
           else
@@ -153,23 +231,23 @@ module TTFunk
 
           case format_sym
           when :array_format
-            @count = top_dict.charstrings_index.count - 1
-            @length = count * element_width
+            @items_count = top_dict.charstrings_index.items_count - 1
+            @length = @items_count * element_width
             @entries = OneBasedArray.new(read(length, 'n*'))
 
           when :range_format8, :range_format16
             # The number of ranges is not explicitly specified in the font.
             # Instead, software utilizing this data simply processes ranges
             # until all glyphs in the font are covered.
-            @count = 0
+            @items_count = 0
             @entries = []
             @length = 0
 
-            until count >= top_dict.charstrings_index.count - 1
+            until @items_count >= top_dict.charstrings_index.items_count - 1
               @length += 1 + element_width
               sid, num_left = read(element_width, element_format)
-              entries << (sid..(sid + num_left))
-              @count += num_left + 1
+              @entries << (sid..(sid + num_left))
+              @items_count += num_left + 1
             end
           end
         end
@@ -178,7 +256,7 @@ module TTFunk
           {
             array_format: 2, # SID
             range_format8: 3, # SID + Card8
-            range_format16: 4 # SID + Card16
+            range_format16: 4, # SID + Card16
           }[fmt]
         end
 
@@ -186,7 +264,7 @@ module TTFunk
           {
             array_format: 'n',
             range_format8: 'nC',
-            range_format16: 'nn'
+            range_format16: 'nn',
           }[fmt]
         end
 
@@ -204,7 +282,7 @@ module TTFunk
           {
             array_format: ARRAY_FORMAT,
             range_format8: RANGE_FORMAT_8,
-            range_format16: RANGE_FORMAT_16
+            range_format16: RANGE_FORMAT_16,
           }[sym]
         end
       end

data/lib/ttfunk/table/cff/charsets/expert.rb

@@ -4,6 +4,7 @@ module TTFunk
   class Table
     class Cff < TTFunk::Table
       module Charsets
+        # Predefinde CFF Expert charset
         EXPERT = OneBasedArray.new(
           [
             'space',
@@ -180,8 +181,8 @@ module TTFunk
             'Ucircumflexsmall',
             'Udieresissmall',
             'Yacutesmall',
-            'Thornsmall'
-          ]
+            'Thornsmall',
+          ],
         ).freeze
       end
     end

data/lib/ttfunk/table/cff/charsets/expert_subset.rb

@@ -4,6 +4,7 @@ module TTFunk
   class Table
     class Cff < TTFunk::Table
       module Charsets
+        # Predefined CFF Expert Subset charset
         EXPERT_SUBSET = OneBasedArray.new(
           [
             'space',
@@ -110,8 +111,8 @@ module TTFunk
             'nineinferior',
             'centinferior',
             'dollarinferior',
-            'periodinferior'
-          ]
+            'periodinferior',
+          ],
         ).freeze
       end
     end

data/lib/ttfunk/table/cff/charsets/iso_adobe.rb

@@ -4,6 +4,7 @@ module TTFunk
   class Table
     class Cff < TTFunk::Table
       module Charsets
+        # Predefined CFF ISOAdobe charset
         ISO_ADOBE = OneBasedArray.new(
           [
             'space',
@@ -232,8 +233,8 @@ module TTFunk
             'ugrave',
             'yacute',
             'ydieresis',
-            'zcaron'
-          ]
+            'zcaron',
+          ],
         ).freeze
       end
     end

data/lib/ttfunk/table/cff/charsets/standard_strings.rb

@@ -4,6 +4,7 @@ module TTFunk
   class Table
     class Cff < TTFunk::Table
       module Charsets
+        # Standard CFF strings
         STANDARD_STRINGS = OneBasedArray.new(
           [
             'space',
@@ -395,8 +396,8 @@ module TTFunk
             'Medium',
             'Regular',
             'Roman',
-            'Semibold'
-          ]
+            'Semibold',
+          ],
         ).freeze
       end
     end

data/lib/ttfunk/table/cff/charsets.rb

@@ -3,6 +3,7 @@
 module TTFunk
   class Table
     class Cff < TTFunk::Table
+      # Predefined CFF data
       module Charsets
         autoload :EXPERT, 'ttfunk/table/cff/charsets/expert'
         autoload :EXPERT_SUBSET, 'ttfunk/table/cff/charsets/expert_subset'

data/lib/ttfunk/table/cff/charstring.rb

@@ -3,7 +3,9 @@
 module TTFunk
   class Table
     class Cff < TTFunk::Table
+      # CFF Charstring.
       class Charstring
+        # Type 2 charstring operators
         CODE_MAP = {
           1 => :hstem,
           3 => :vstem,
@@ -28,18 +30,29 @@ module TTFunk
           28 => :shortint,
           29 => :callgsubr,
           30 => :vhcurveto,
-          31 => :hvcurveto
+          31 => :hvcurveto,
         }.freeze
 
+        # Type 2 Flex operators.
         FLEX_CODE_MAP = {
           35 => :flex,
           34 => :hflex,
           36 => :hflex1,
-          37 => :flex1
+          37 => :flex1,
         }.freeze
 
-        attr_reader :glyph_id, :raw
+        # Glyph ID.
+        # @return [Integer]
+        attr_reader :glyph_id
 
+        # Encoded charstring.
+        # @return [String]
+        attr_reader :raw
+
+        # @param glyph_id [Integer]
+        # @param top_dict [TTFunk::Table:Cff::TopDict]
+        # @param font_dict [TTFunk::Table:Cff::FontDict]
+        # @param raw [String]
         def initialize(glyph_id, top_dict, font_dict, raw)
           @glyph_id = glyph_id
           @top_dict = top_dict
@@ -66,6 +79,9 @@ module TTFunk
           @y = 0
         end
 
+        # Get path representation of this charstring.
+        #
+        # @return [TTFunk::Table::Cff::Path]
         def path
           @path || begin
             @path = Path.new
@@ -74,6 +90,9 @@ module TTFunk
           end
         end
 
+        # Get a TrueType-compatible glyph representation of this charstring.
+        #
+        # @return [TTFunk::Table::Glyf::PathBased]
         def glyph
           @glyph ||=
             begin
@@ -82,19 +101,21 @@ module TTFunk
             end
         end
 
+        # Get path representation of this charstring at the specified font size.
+        #
+        # @param x [Integer, Float] new horizontal position.
+        # @param y [Integer, Float] new vertical position.
+        # @param font_size [Integer, Float] font size.
+        # @return [TTFunk::Table::Cff::Path]
         def render(x: 0, y: 0, font_size: 72)
           path.render(
             x: x,
             y: y,
             font_size: font_size,
-            units_per_em: @top_dict.file.header.units_per_em
+            units_per_em: @top_dict.file.header.units_per_em,
           )
         end
 
-        def encode
-          raw
-        end
-
         private
 
         def parse!
@@ -106,22 +127,22 @@ module TTFunk
             next if code == 11
 
             if code >= 32 && code <= 246
-              @stack << code - 139
+              @stack << (code - 139)
             elsif (m = CODE_MAP[code])
               __send__(m)
             elsif code >= 247 && code <= 250
               b0 = code
               b1 = @data[@index]
               @index += 1
-              @stack << (b0 - 247) * 256 + b1 + 108
+              @stack << (((b0 - 247) * 256) + b1 + 108)
             elsif code >= 251 && code <= 254
               b0 = code
               b1 = @data[@index]
               @index += 1
-              @stack << -(b0 - 251) * 256 - b1 - 108
+              @stack << ((-(b0 - 251) * 256) - b1 - 108)
             else
               b1, b2, b3, b4 = read_bytes(4)
-              @stack << ((b1 << 24) | (b2 << 16) | (b3 << 8) | b4) / 65_536
+              @stack << (((b1 << 24) | (b2 << 16) | (b3 << 8) | b4) / 65_536)
             end
           end
         end

data/lib/ttfunk/table/cff/charstrings_index.rb

@@ -3,28 +3,34 @@
 module TTFunk
   class Table
     class Cff < TTFunk::Table
+      # CFF Charstrings Index.
       class CharstringsIndex < TTFunk::Table::Cff::Index
+        # Top dict.
+        # @return [TTFunk::Table::Cff::TopDict]
         attr_reader :top_dict
 
+        # @overload initialize(top_dict, file, offset, length = nil)
+        #   @param top_dict [TTFunk::Table:Cff::TopDict]
+        #   @param file [TTFunk::File]
+        #   @param offset [Integer]
+        #   @param length [Integer]
         def initialize(top_dict, *remaining_args)
           super(*remaining_args)
           @top_dict = top_dict
         end
 
-        def [](index)
-          entry_cache[index] ||= TTFunk::Table::Cff::Charstring.new(
-            index, top_dict, font_dict_for(index), super
-          )
-        end
+        private
 
-        # gets passed a mapping of new => old glyph ids
-        def encode(mapping)
-          super() do |_entry, index|
-            self[mapping[index]].encode if mapping.include?(index)
-          end
+        def decode_item(index, _offset, _length)
+          TTFunk::Table::Cff::Charstring.new(index, top_dict, font_dict_for(index), super)
         end
 
-        private
+        def encode_items(charmap)
+          charmap
+            .reject { |code, mapping| mapping[:new].zero? && !code.zero? }
+            .sort_by { |_code, mapping| mapping[:new] }
+            .map { |(_code, mapping)| items[mapping[:old]] }
+        end
 
         def font_dict_for(index)
           # only CID-keyed fonts contain an FD selector and font dicts