ttfunk 1.7.0 → 1.8.0

data/lib/ttfunk/table/cmap/format12.rb

@@ -3,10 +3,30 @@
 module TTFunk
   class Table
     class Cmap
+      # Format 12: Segmented coverage.
+      #
+      # This module conditionally extends {TTFunk::Table::Cmap::Subtable}.
       module Format12
+        # Language.
+        # @return [Integer]
         attr_reader :language
+
+        # Code map.
+        # @return [Hash{Integer => Integer}]
         attr_reader :code_map
 
+        # Encode the encoding record to format 12.
+        #
+        # @param charmap [Hash{Integer => Integer}] a hash mapping character
+        #   codes to glyph IDs from the original font.
+        # @return [Hash]
+        #   * `:charmap` (<tt>Hash{Integer => Hash}</tt>) keys are the characrers in
+        #     `charset`, values are hashes:
+        #     * `:old` (<tt>Integer</tt>) - glyph ID in the original font.
+        #     * `:new` (<tt>Integer</tt>) - glyph ID in the subset font.
+        #     that maps the characters in charmap to a
+        #   * `:subtable` (<tt>String</tt>) - serialized encoding record.
+        #   * `:max_glyph_id` (<tt>Integer</tt>) - maximum glyph ID in the new font.
         def self.encode(charmap)
           next_id = 0
           glyph_map = { 0 => 0 }
@@ -32,23 +52,30 @@ module TTFunk
             end
 
           subtable = [
-            12, 0, 16 + 12 * range_lengths.size, 0, range_lengths.size
+            12, 0, 16 + (12 * range_lengths.size), 0, range_lengths.size,
           ].pack('nnNNN')
           range_lengths.each_with_index do |length, i|
             firstglyph = range_firstglyphs[i]
             firstcode = range_firstcodes[i]
             subtable << [
-              firstcode, firstcode + length - 1, firstglyph
+              firstcode, firstcode + length - 1, firstglyph,
             ].pack('NNN')
           end
 
           { charmap: new_map, subtable: subtable, max_glyph_id: next_id + 1 }
         end
 
+        # Get glyph ID for character code.
+        #
+        # @param code [Integer] character code.
+        # @return [Integer] glyph ID.
         def [](code)
           @code_map[code] || 0
         end
 
+        # Is this encoding record format supported?
+        #
+        # @return [true]
         def supported?
           true
         end

data/lib/ttfunk/table/cmap/subtable.rb

@@ -5,21 +5,54 @@ require_relative '../../reader'
 module TTFunk
   class Table
     class Cmap
+      # Character to Glyph Index encoding record.
+      # This class can be extended with a format-specific
+      #
+      # @see TTFunk::Table::Cmap::Format00
+      # @see TTFunk::Table::Cmap::Format04
+      # @see TTFunk::Table::Cmap::Format06
+      # @see TTFunk::Table::Cmap::Format10
+      # @see TTFunk::Table::Cmap::Format12
       class Subtable
         include Reader
 
+        # Platform ID.
+        # @return [Integer]
         attr_reader :platform_id
+
+        # Platform-specific encoding ID.
+        # @return [Integere]
         attr_reader :encoding_id
+
+        # Record encoding format.
+        # @return [Integer]
         attr_reader :format
 
+        # Most used encoding mappings.
         ENCODING_MAPPINGS = {
           mac_roman: { platform_id: 1, encoding_id: 0 }.freeze,
           # Use microsoft unicode, instead of generic unicode, for optimal
           # Windows support
           unicode: { platform_id: 3, encoding_id: 1 }.freeze,
-          unicode_ucs4: { platform_id: 3, encoding_id: 10 }.freeze
+          unicode_ucs4: { platform_id: 3, encoding_id: 10 }.freeze,
         }.freeze
 
+        # Encode encoding record.
+        #
+        # @param charmap [Hash{Integer => Integer}] keys are code points in the
+        #   used encoding, values are Unicode code points.
+        # @param encoding [Symbol] - one of the encodign mapping in
+        #   {ENCODING_MAPPINGS}
+        # @return [Hash]
+        #   * `:platform_id` (<tt>Integer</tt>) - Platform ID of this encoding record.
+        #   * `:encoding_id` (<tt>Integer</tt>) - Encodign ID of this encoding record.
+        #   * `:subtable` (<tt>String</tt>) - encoded encoding record.
+        #   * `:max_glyph_id` (<tt>Integer</tt>) - maximum glyph ID in this encoding
+        #     record.
+        #   * `:charmap` (<tt>Hash{Integer => Hash}</tt>) - keys are codepoints in this
+        #     encoding record, values are hashes:
+        #     * `:new` - new glyph ID.
+        #     * `:old` - glyph ID in the original font.
         def self.encode(charmap, encoding)
           case encoding
           when :mac_roman
@@ -43,11 +76,13 @@ module TTFunk
               mapping[:platform_id],
               mapping[:encoding_id],
               12,
-              result[:subtable]
-            ].pack('nnNA*')
+              result[:subtable],
+            ].pack('nnNA*'),
           )
         end
 
+        # @param file [TTFunk::File]
+        # @param table_start [Integer]
         def initialize(file, table_start)
           @file = file
           @platform_id, @encoding_id, @offset = read(8, 'nnN')
@@ -68,16 +103,25 @@ module TTFunk
           end
         end
 
+        # Is this an encoding record for Unicode?
+        #
+        # @return [Boolean]
         def unicode?
-          platform_id == 3 && (encoding_id == 1 || encoding_id == 10) &&
-            format != 0 ||
-            platform_id.zero? && format != 0
+          (platform_id == 3 && (encoding_id == 1 || encoding_id == 10) && format != 0) ||
+            (platform_id.zero? && format != 0)
         end
 
+        # Is this encoding record format supported?
+        #
+        # @return [Boolean]
         def supported?
           false
         end
 
+        # Get glyph ID for character code.
+        #
+        # @param _code [Integer] character code.
+        # @return [Integer] glyph ID.
         def [](_code)
           raise NotImplementedError, "cmap format #{@format} is not supported"
         end

data/lib/ttfunk/table/cmap.rb

@@ -2,10 +2,28 @@
 
 module TTFunk
   class Table
+    # Character to Glyph Index Mapping (`cmap`) table.
     class Cmap < Table
+      # Table version.
+      # @return [Integer]
       attr_reader :version
+
+      # Encoding tables.
+      # @return [Array<TTFunk::Table::Cmap::Subtable>]
       attr_reader :tables
 
+      # Encode table.
+      #
+      # @param charmap [Hash{Integer => Integer}]
+      # @param encoding [Symbol]
+      # @return [Hash]
+      #   * `:charmap` (<tt>Hash{Integer => Hash}</tt>) keys are the characrers in
+      #     `charset`, values are hashes:
+      #     * `:old` (<tt>Integer</tt>) - glyph ID in the original font.
+      #     * `:new` (<tt>Integer</tt>) - glyph ID in the subset font.
+      #     that maps the characters in charmap to a
+      #   * `:table` (<tt>String</tt>) - serialized table.
+      #   * `:max_glyph_id` (<tt>Integer</tt>) - maximum glyph ID in the new font.
       def self.encode(charmap, encoding)
         result = Cmap::Subtable.encode(charmap, encoding)
 
@@ -14,6 +32,9 @@ module TTFunk
         result
       end
 
+      # Get Unicode encoding records.
+      #
+      # @return [Array<TTFunk::Table::Cmap::Subtable>]
       def unicode
         # Because most callers just call .first on the result, put tables with
         # highest-number format first. Unsupported formats will be ignored.

data/lib/ttfunk/table/dsig.rb

@@ -2,10 +2,30 @@
 
 module TTFunk
   class Table
+    # Digital Signature (`DSIG`) table.
     class Dsig < Table
+      # Signature record.
       class SignatureRecord
-        attr_reader :format, :length, :offset, :signature
+        # Format of the signature.
+        # @return [Integer]
+        attr_reader :format
 
+        # Length of signature in bytes.
+        # @return [Integer]
+        attr_reader :length
+
+        # Offset to the signature block from the beginning of the table.
+        # @return [Integer]
+        attr_reader :offset
+
+        # Signature PKCS#7 packet.
+        # @return [String]
+        attr_reader :signature
+
+        # @param format [Integer]
+        # @param length [Integer]
+        # @param offset [Integer]
+        # @param signature [String]
         def initialize(format, length, offset, signature)
           @format = format
           @length = length
@@ -14,10 +34,28 @@ module TTFunk
         end
       end
 
-      attr_reader :version, :flags, :signatures
+      # Version umber of this table.
+      # @return [Integer]
+      attr_reader :version
+
+      # Permission flags.
+      # @return [Integer]
+      attr_reader :flags
+
+      # Signature records.
+      # @return [Array<SignatureRecord>]
+      attr_reader :signatures
 
+      # Table tag.
       TAG = 'DSIG'
 
+      # Encode table.
+      #
+      # **Note**: all signatures will be lost. This encodes an empty table
+      # regardless whether the supplied table contains any signtaures or not.
+      #
+      # @param dsig [TTFunk::Table::Dsig]
+      # @return [String]
       def self.encode(dsig)
         return unless dsig
 
@@ -26,6 +64,9 @@ module TTFunk
         [dsig.version, 0, 0].pack('Nnn')
       end
 
+      # Table tag.
+      #
+      # @return [String]
       def tag
         TAG
       end
@@ -36,16 +77,16 @@ module TTFunk
         @version, num_signatures, @flags = read(8, 'Nnn')
 
         @signatures =
-          Array.new(num_signatures) do
+          Array.new(num_signatures) {
             format, length, sig_offset = read(12, 'N3')
             signature =
-              parse_from(offset + sig_offset) do
+              parse_from(offset + sig_offset) {
                 _, _, sig_length = read(8, 'nnN')
                 read(sig_length, 'C*')
-              end
+              }
 
             SignatureRecord.new(format, length, sig_offset, signature)
-          end
+          }
       end
     end
   end

data/lib/ttfunk/table/glyf/compound.rb

@@ -5,32 +5,92 @@ require_relative '../../reader'
 module TTFunk
   class Table
     class Glyf
+      # Composite TrueType glyph.
       class Compound
         include Reader
 
+        # Flags bit 0: arg1 and arg2 are words.
         ARG_1_AND_2_ARE_WORDS = 0x0001
+
+        # Flags bit 3: there is a simple scale for the component.
         WE_HAVE_A_SCALE = 0x0008
+
+        # Flags bit 5: at least one more glyph after this one.
         MORE_COMPONENTS = 0x0020
+
+        # Flags bit 6: the x direction will use a different scale from the
+        # y direction.
         WE_HAVE_AN_X_AND_Y_SCALE = 0x0040
+
+        # Flags bit 7: there is a 2 by 2 transformation that will be used to
+        # scale the component.
         WE_HAVE_A_TWO_BY_TWO = 0x0080
+
+        # Flags bit 8: following the last component are instructions for the
+        # composite character.
         WE_HAVE_INSTRUCTIONS = 0x0100
 
-        attr_reader :id, :raw
+        # Glyph ID.
+        # @return [Integer]
+        attr_reader :id
+
+        # Binary serialization of this glyph.
+        # @return [String]
+        attr_reader :raw
+
+        # Number of contours in this glyph.
+        # @return [Integer]
         attr_reader :number_of_contours
-        attr_reader :x_min, :y_min, :x_max, :y_max
+
+        # Minimum x for coordinate.
+        # @return [Integer]
+        attr_reader :x_min
+
+        # Minimum y for coordinate.
+        # @return [Integer]
+        attr_reader :y_min
+
+        # Maximum x for coordinate.
+        # @return [Integer]
+        attr_reader :x_max
+
+        # Maximum y for coordinate.
+        # @return [Integer]
+        attr_reader :y_max
+
+        # IDs of compound glyphs.
         attr_reader :glyph_ids
 
+        # Component glyph.
+        #
+        # @!attribute [rw] flags
+        #   Component flag.
+        #   @return [Integer]
+        # @!attribute [rw] glyph_index
+        #   Glyph index of component.
+        #   @return [Integer]
+        # @!attribute [rw] arg1
+        #   x-offset for component or point number.
+        #   @return [Integer]
+        # @!attribute [rw] arg2
+        #   y-offset for component or point number.
+        #   @return [Integer]
+        # @!attribute [rw] transform
+        #   Transformation.
+        #   @return []
         Component = Struct.new(:flags, :glyph_index, :arg1, :arg2, :transform)
 
+        # @param id [Integer] glyph ID.
+        # @param raw [String]
         def initialize(id, raw)
           @id = id
           @raw = raw
           io = StringIO.new(raw)
 
           @number_of_contours, @x_min, @y_min, @x_max, @y_max =
-            io.read(10).unpack('n*').map do |i|
+            io.read(10).unpack('n*').map { |i|
               BinUtils.twos_comp_to_int(i, bit_width: 16)
-            end
+            }
 
           # Because TTFunk only cares about glyphs insofar as they (1) provide
           # a bounding box for each glyph, and (2) can be rewritten into a
@@ -48,9 +108,9 @@ module TTFunk
           loop do
             flags, glyph_id = @raw[offset, 4].unpack('n*')
             @glyph_ids << glyph_id
-            @glyph_id_offsets << offset + 2
+            @glyph_id_offsets << (offset + 2)
 
-            break unless flags & MORE_COMPONENTS != 0
+            break if (flags & MORE_COMPONENTS).zero?
 
             offset += 4
 
@@ -71,10 +131,17 @@ module TTFunk
           end
         end
 
+        # Is this a composite glyph?
+        # @return [true]
         def compound?
           true
         end
 
+        # Recode glyph.
+        #
+        # @param mapping [Hash{Integer => Integer}] a hash mapping old glyph IDs
+        #   to new glyph IDs.
+        # @return [String]
         def recode(mapping)
           result = raw.dup
           new_ids = glyph_ids.map { |id| mapping[id] }

data/lib/ttfunk/table/glyf/path_based.rb

@@ -3,11 +3,42 @@
 module TTFunk
   class Table
     class Glyf
+      # TrueType-compatible representation of a CFF glyph.
       class PathBased
-        attr_reader :path, :horizontal_metrics
-        attr_reader :x_min, :y_min, :x_max, :y_max
-        attr_reader :left_side_bearing, :right_side_bearing
+        # Glyph outline.
+        # @return [TTFunk::Table::Cff::Path]
+        attr_reader :path
 
+        # Glyph horizontal metrics.
+        # @return [TTFunk::Table::Hmtx::HorizontalMetric]
+        attr_reader :horizontal_metrics
+
+        # Minimum X.
+        # @return [Integer, Float]
+        attr_reader :x_min
+
+        # Minimum Y.
+        # @return [Integer, Float]
+        attr_reader :y_min
+
+        # Maximum X.
+        # @return [Integer, Float]
+        attr_reader :x_max
+
+        # Maximum Y.
+        # @return [Integer, Float]
+        attr_reader :y_max
+
+        # Left side bearing.
+        # @return [Integer, Float]
+        attr_reader :left_side_bearing
+
+        # Rigth side bearing.
+        # @return [Integer, Float]
+        attr_reader :right_side_bearing
+
+        # @param path [TTFunk::Table::Cff::Path]
+        # @param horizontal_metrics [TTFunk::Table::Hmtx::HorizontalMetric]
         def initialize(path, horizontal_metrics)
           @path = path
           @horizontal_metrics = horizontal_metrics
@@ -34,10 +65,16 @@ module TTFunk
             (@x_max - @x_min)
         end
 
+        # Number of contour.
+        #
+        # @return [Integer]
         def number_of_contours
           path.number_of_contours
         end
 
+        # Is this glyph compound?
+        #
+        # @return [false]
         def compound?
           false
         end

data/lib/ttfunk/table/glyf/simple.rb

@@ -5,36 +5,81 @@ require_relative '../../reader'
 module TTFunk
   class Table
     class Glyf
+      # Simple TrueType glyph
       class Simple
-        attr_reader :id, :raw
+        # Glyph ID.
+        # @return [Integer]
+        attr_reader :id
+
+        # Binary serialization of this glyph.
+        # @return [String]
+        attr_reader :raw
+
+        # Number of contours in this glyph.
+        # @return [Integer]
         attr_reader :number_of_contours
-        attr_reader :x_min, :y_min, :x_max, :y_max
+
+        # Minimum x for coordinate.
+        # @return [Integer]
+        attr_reader :x_min
+
+        # Minimum y for coordinate.
+        # @return [Integer]
+        attr_reader :y_min
+
+        # Maximum x for coordinate.
+        # @return [Integer]
+        attr_reader :x_max
+
+        # Maximum y for coordinate.
+        # @return [Integer]
+        attr_reader :y_max
+
+        # Point indices for the last point of each contour.
+        # @return [Array<Integer>]
         attr_reader :end_points_of_contours
-        attr_reader :instruction_length, :instructions
 
+        # Total number of bytes for instructions.
+        # @return [Integer]
+        attr_reader :instruction_length
+
+        # Instruction byte code.
+        # @return [Array<Integer>]
+        attr_reader :instructions
+
+        # @param id [Integer] glyph ID.
+        # @param raw [String]
         def initialize(id, raw)
           @id = id
           @raw = raw
           io = StringIO.new(raw)
 
           @number_of_contours, @x_min, @y_min, @x_max, @y_max =
-            io.read(10).unpack('n*').map do |i|
+            io.read(10).unpack('n*').map { |i|
               BinUtils.twos_comp_to_int(i, bit_width: 16)
-            end
+            }
 
           @end_points_of_contours = io.read(number_of_contours * 2).unpack('n*')
           @instruction_length = io.read(2).unpack1('n')
           @instructions = io.read(instruction_length).unpack('C*')
         end
 
+        # Is this glyph compound?
+        # @return [false]
         def compound?
           false
         end
 
+        # Recode glyph.
+        #
+        # @param _mapping Unused, here for API compatibility.
+        # @return [String]
         def recode(_mapping)
           raw
         end
 
+        # End point index of last contour.
+        # @return [Integer]
         def end_point_of_last_contour
           end_points_of_contours.last + 1
         end

data/lib/ttfunk/table/glyf.rb

@@ -4,15 +4,18 @@ require_relative '../table'
 
 module TTFunk
   class Table
+    # Glyph Data (`glyf`) table.
     class Glyf < Table
-      # Accepts a hash mapping (old) glyph-ids to glyph objects, and a hash
-      # mapping old glyph-ids to new glyph-ids.
+      # Encode table.
       #
-      # Returns a hash containing:
-      #
-      # * :table - a string representing the encoded 'glyf' table containing
-      #   the given glyphs.
-      # * :offsets - an array of offsets for each glyph
+      # @param glyphs [Hash] a hash mapping (old) glyph-ids to glyph objects
+      # @param new_to_old [Hash{Integer => Integer}] a hash mapping new glyph
+      #   IDs to glyph IDs in the original font.
+      # @param old_to_new [Hash{Integer => Integer}] a hash mapping old glyph
+      #   IDs to new glyph IDs.
+      # @return [Hash]
+      #   * `:table` (<tt>String</tt>) - encoded table.
+      #   * `:offsets` (<tt>Array\<Integer></tt>) - glyph offsets in the table.
       def self.encode(glyphs, new_to_old, old_to_new)
         result = { table: +'', offsets: [] }
 
@@ -28,6 +31,11 @@ module TTFunk
         result
       end
 
+      # Get glyph by ID.
+      #
+      # @param glyph_id [Integer]
+      # @return [TTFunk::Table::Glyf::Simple, TTFunk::Table::Glyf::Compound,
+      #   nil]
       def for(glyph_id)
         return @cache[glyph_id] if @cache.key?(glyph_id)