ttfunk 1.7.0 → 1.8.0

data/lib/ttfunk/table/os2.rb

@@ -5,44 +5,147 @@ require 'set'
 
 module TTFunk
   class Table
+    # OS/2 and Windows Metrics (`OS/2`) table
     class OS2 < Table
+      # Table version.
+      # @return [Integer]
       attr_reader :version
 
+      # Average weighted escapement.
+      # @return [Integer]
       attr_reader :ave_char_width
+
+      # Weight class.
+      # @return [Integer]
       attr_reader :weight_class
+
+      # Width class.
+      # @return [Integer]
       attr_reader :width_class
+
+      # Type flags.
+      # @return [Integer]
       attr_reader :type
+
+      # Subscript horizontal font size.
+      # @return [Integer]
       attr_reader :y_subscript_x_size
+
+      # Subscript vertical font size.
+      # @return [Integer]
       attr_reader :y_subscript_y_size
+
+      # Subscript x offset.
+      # @return [Integer]
       attr_reader :y_subscript_x_offset
+
+      # Subscript y offset.
+      # @return [Integer]
       attr_reader :y_subscript_y_offset
+
+      # Superscript horizontal font size.
+      # @return [Integer]
       attr_reader :y_superscript_x_size
+
+      # Superscript vertical font size.
+      # @return [Integer]
       attr_reader :y_superscript_y_size
+
+      # Superscript x offset.
+      # @return [Integer]
       attr_reader :y_superscript_x_offset
+
+      # Superscript y offset.
+      # @return [Integer]
       attr_reader :y_superscript_y_offset
+
+      # Strikeout size.
+      # @return [Integer]
       attr_reader :y_strikeout_size
+
+      # Strikeout position.
+      # @return [Integer]
       attr_reader :y_strikeout_position
+
+      # Font-family class and subclass.
+      # @return [Integer]
       attr_reader :family_class
+
+      # PANOSE classification number.
+      # @return [Integer]
       attr_reader :panose
+
+      # Unicode Character Range.
+      # @return [Integer]
       attr_reader :char_range
+
+      # Font Vendor Identification.
+      # @return [String]
       attr_reader :vendor_id
+
+      # Font selection flags.
+      # @return [Integer]
       attr_reader :selection
+
+      # The minimum Unicode index (character code) in this font.
+      # @return [Integer]
       attr_reader :first_char_index
+
+      # The maximum Unicode index (character code) in this font.
+      # @return [Integer]
       attr_reader :last_char_index
 
+      # The typographic ascender for this font.
+      # @return [Integer]
       attr_reader :ascent
+
+      # The typographic descender for this font.
+      # @return [Integer]
       attr_reader :descent
+
+      # The typographic line gap for this font.
+      # @return [Integer]
       attr_reader :line_gap
+
+      # The "Windows ascender" metric.
+      # @return [Integer]
       attr_reader :win_ascent
+
+      # The "Windows descender" metric.
+      # @return [Integer]
       attr_reader :win_descent
+
+      # Code Page Character Range.
+      # @return [Integer]
       attr_reader :code_page_range
 
+      # The distance between the baseline and the approximate height of
+      # non-ascending lowercase letters.
+      # @return [Integer]
       attr_reader :x_height
+
+      # The distance between the baseline and the approximate height of
+      # uppercase letters.
+      # @return [Integer]
       attr_reader :cap_height
+
+      # The Unicode code point, in UTF-16 encoding, of a character that can be
+      # used for a default glyph if a requested character is not supported in
+      # the font.
+      # @return [Integer]
       attr_reader :default_char
+
+      # The Unicode code point, in UTF-16 encoding, of a character that can be
+      # used as a default break character.
+      # @return [Integer]
       attr_reader :break_char
+
+      # The maximum length of a target glyph context for any feature in this
+      # font.
+      # @return [Integer]
       attr_reader :max_context
 
+      # Code page bits.
       CODE_PAGE_BITS = {
         1252 => 0,
         1250 => 1,
@@ -75,9 +178,10 @@ module TTFunk
         737 => 60,
         708 => 61,
         850 => 62,
-        437 => 63
+        437 => 63,
       }.freeze
 
+      # Unicode blocks.
       UNICODE_BLOCKS = {
         (0x0000..0x007F) => 0,
         (0x0080..0x00FF) => 1,
@@ -247,17 +351,29 @@ module TTFunk
         (0x10280..0x1029F) => 121,
         (0x10920..0x1093F) => 121,
         (0x1F030..0x1F09F) => 122,
-        (0x1F000..0x1F02F) => 122
+        (0x1F000..0x1F02F) => 122,
       }.freeze
 
+      # Indicates that font supports supplementary characters.
       UNICODE_MAX = 0xFFFF
-      UNICODE_RANGES = UNICODE_BLOCKS.keys.freeze
+
+      # Unicode block ranges.
+      UNICODE_RANGES = UNICODE_BLOCKS.keys.sort_by(&:max).freeze
+
+      # Start chracter for average character width calculation.
       LOWERCASE_START = 'a'.ord
+
+      # End chracter for average character width calculation.
       LOWERCASE_END = 'z'.ord
+
+      # Number of chracters for average character width calculation.
       LOWERCASE_COUNT = (LOWERCASE_END - LOWERCASE_START) + 1
+
+      # Space character code point.
       CODEPOINT_SPACE = 32
-      SPACE_GLYPH_MISSING_ERROR = "Space glyph (0x#{CODEPOINT_SPACE.to_s(16)})"\
-        ' must be included in the font'
+
+      # Error message for missing space character.
+      SPACE_GLYPH_MISSING_ERROR = "Space glyph (0x#{CODEPOINT_SPACE.to_s(16)}) must be included in the font"
 
       # Used to calculate the xAvgCharWidth field.
       # From https://docs.microsoft.com/en-us/typography/opentype/spec/os2:
@@ -272,16 +388,26 @@ module TTFunk
       # 26 letters in the Latin alphabet. Each weight is the relative
       # frequency of that letter in the English language.
       WEIGHT_SPACE = 166
+
+      # chracter weights for average character width calculation.
       WEIGHT_LOWERCASE = [
         64, 14, 27, 35, 100, 20, 14, 42, 63, 3, 6, 35, 20,
-        56, 56, 17, 4, 49, 56, 71, 31, 10, 18, 3, 18, 2
+        56, 56, 17, 4, 49, 56, 71, 31, 10, 18, 3, 18, 2,
       ].freeze
 
+      # Table tag.
+      # @return [String]
       def tag
         'OS/2'
       end
 
       class << self
+        # Encode table.
+        #
+        # @param os2 [TTFunk::Table::OS2]
+        # @param subset [TTFunk::Subset::MacRoman, TTFunk::Subset::Windows1252,
+        #   TTFunk::Subset::Unicode, TTFunk::Subset::Unicode8Bit]
+        # @return [String]
         def encode(os2, subset)
           result = ''.b
           result << [
@@ -291,7 +417,7 @@ module TTFunk
             os2.y_subscript_y_offset, os2.y_superscript_x_size,
             os2.y_superscript_y_size, os2.y_superscript_x_offset,
             os2.y_superscript_y_offset, os2.y_strikeout_size,
-            os2.y_strikeout_position, os2.family_class
+            os2.y_strikeout_position, os2.family_class,
           ].pack('n*')
 
           result << os2.panose
@@ -301,7 +427,7 @@ module TTFunk
             .slice_int(
               new_char_range.value,
               bit_width: 32,
-              slice_count: 4
+              slice_count: 4,
             )
             .pack('N*')
 
@@ -322,27 +448,27 @@ module TTFunk
           last_char_index = [code_points.last || 0, UNICODE_MAX].min
 
           result << [
-            os2.selection, first_char_index, last_char_index
+            os2.selection, first_char_index, last_char_index,
           ].pack('n*')
 
           if os2.version.positive?
             result << [
               os2.ascent, os2.descent, os2.line_gap,
-              os2.win_ascent, os2.win_descent
+              os2.win_ascent, os2.win_descent,
             ].pack('n*')
 
             result << BinUtils
               .slice_int(
                 code_pages_for(subset).value,
                 bit_width: 32,
-                slice_count: 2
+                slice_count: 2,
               )
               .pack('N*')
 
             if os2.version > 1
               result << [
                 os2.x_height, os2.cap_height, os2.default_char,
-                os2.break_char, os2.max_context
+                os2.break_char, os2.max_context,
               ].pack('n*')
             end
           end
@@ -380,13 +506,15 @@ module TTFunk
 
         def group_original_code_points_by_bit(os2)
           Hash.new { |h, k| h[k] = [] }.tap do |result|
-            os2.file.cmap.unicode.first.code_map.each_key do |code_point|
-              # find corresponding bit
-              range = UNICODE_RANGES.find { |r| r.cover?(code_point) }
-
-              if (bit = UNICODE_BLOCKS[range])
-                result[bit] << code_point
+            code_points = os2.file.cmap.unicode.first.code_map.keys.sort
+            UNICODE_RANGES.each do |r|
+              code_points = code_points.drop_while { |p| p < r.min }
+              code_points.take_while { |p| p <= r.max }.each do |code_point|
+                if (bit = UNICODE_BLOCKS[r])
+                  result[bit] << code_point
+                end
               end
+              code_points = code_points.drop_while { |p| p <= r.max }
             end
           end
         end
@@ -405,7 +533,7 @@ module TTFunk
 
           # use new -> old glyph mapping in order to include compound glyphs
           # in the calculation
-          subset.new_to_old_glyph.each do |_, old_gid|
+          subset.new_to_old_glyph.each_value do |old_gid|
             if (metric = os2.file.horizontal_metrics.for(old_gid))
               total_width += metric.advance_width
               num_glyphs += 1 if metric.advance_width.positive?
@@ -456,7 +584,7 @@ module TTFunk
 
           # use new -> old glyph mapping in order to include compound glyphs
           # in the calculation
-          subset.new_to_old_glyph.each do |_, old_gid|
+          subset.new_to_old_glyph.each_value do |old_gid|
             if (metric = os2.file.horizontal_metrics.for(old_gid))
               total_width += metric.advance_width
             end
@@ -481,9 +609,7 @@ module TTFunk
           @y_strikeout_position, @family_class = read_signed(12)
         @panose = io.read(10)
 
-        @char_range = BitField.new(
-          BinUtils.stitch_int(read(16, 'N*'), bit_width: 32)
-        )
+        @char_range = BitField.new(BinUtils.stitch_int(read(16, 'N*'), bit_width: 32))
 
         @vendor_id = io.read(4)
         @selection, @first_char_index, @last_char_index = read(6, 'n*')
@@ -491,9 +617,7 @@ module TTFunk
         if @version.positive?
           @ascent, @descent, @line_gap = read_signed(3)
           @win_ascent, @win_descent = read(4, 'nn')
-          @code_page_range = BitField.new(
-            BinUtils.stitch_int(read(8, 'N*'), bit_width: 32)
-          )
+          @code_page_range = BitField.new(BinUtils.stitch_int(read(8, 'N*'), bit_width: 32))
 
           if @version > 1
             @x_height, @cap_height = read_signed(2)

data/lib/ttfunk/table/post/format10.rb

@@ -3,7 +3,10 @@
 module TTFunk
   class Table
     class Post
+      # Version 1.0 provides glyph names for standard 258 glyphs in the standard
+      # Macintosh TrueType font file.
       module Format10
+        # Glyph names.
         POSTSCRIPT_GLYPHS = %w[
           .notdef .null nonmarkingreturn space exclam quotedbl numbersign dollar
           percent ampersand quotesingle parenleft parenright asterisk plus comma
@@ -36,6 +39,10 @@ module TTFunk
           scedilla Cacute cacute Ccaron ccaron dcroat
         ].freeze
 
+        # Get glyph name for character code.
+        #
+        # @param code [Integer]
+        # @return [String]
         def glyph_for(code)
           POSTSCRIPT_GLYPHS[code] || '.notdef'
         end

data/lib/ttfunk/table/post/format20.rb

@@ -6,9 +6,18 @@ require 'stringio'
 module TTFunk
   class Table
     class Post
+      # Version 2.0 is used for fonts that use glyph names that are not in the
+      # set of Macintosh glyph names. A given font may map some of its glyphs to
+      # the standard Macintosh glyph names, and some to its own custom names.
+      # A version 2.0 `post` table can be used in fonts with TrueType or CFF
+      # version 2 outlines.
       module Format20
         include Format10
 
+        # Get glyph name for character code.
+        #
+        # @param code [Integer]
+        # @return [String]
         def glyph_for(code)
           index = @glyph_name_index[code]
           return '.notdef' unless index

data/lib/ttfunk/table/post/format30.rb

@@ -3,7 +3,13 @@
 module TTFunk
   class Table
     class Post
+      # Version 3.0 specifies that no PostScript name information is provided
+      # for the glyphs in this font file.
       module Format30
+        # Get glyph name for character code.
+        #
+        # @param _code [Integer]
+        # @return [String]
         def glyph_for(_code)
           '.notdef'
         end

data/lib/ttfunk/table/post/format40.rb

@@ -3,7 +3,12 @@
 module TTFunk
   class Table
     class Post
+      # Version 4.0 names glyphs by their character code.
       module Format40
+        # Get glyph name for character code.
+        #
+        # @param code [Integer]
+        # @return [String]
         def glyph_for(code)
           @map[code] || 0xFFFF
         end

data/lib/ttfunk/table/post.rb

@@ -4,33 +4,93 @@ require_relative '../table'
 
 module TTFunk
   class Table
+    # PostScript (`post`) table.
+    #
+    # This class can be extended with version-specific modules.
+    #
+    # @see TTFunk::Table::Post::Format10
+    # @see TTFunk::Table::Post::Format20
+    # @see TTFunk::Table::Post::Format30
+    # @see TTFunk::Table::Post::Format40
     class Post < Table
+      # Table version.
+      # @return [Integer]
       attr_reader :format
+
+      # Italic angle in counter-clockwise degrees from the vertical.
+      # @return [Integer]
       attr_reader :italic_angle
+
+      # Suggested distance of the top of the underline from the baseline
+      # @return [Integer]
       attr_reader :underline_position
+
+      # Suggested values for the underline thickness.
+      # @return [Integer]
       attr_reader :underline_thickness
+
+      # 0 if the font is proportionally spaced, non-zero if the font is not
+      # proportionally spaced.
+      # @return [Integer]
       attr_reader :fixed_pitch
+
+      # Minimum memory usage when an OpenType font is downloaded.
+      # @return [Integer]
       attr_reader :min_mem_type42
+
+      # Maximum memory usage when an OpenType font is downloaded.
+      # @return [Integer]
       attr_reader :max_mem_type42
+
+      # Minimum memory usage when an OpenType font is downloaded as
+      # a Type 1 font.
+      # @return [Integer]
       attr_reader :min_mem_type1
+
+      # Maximum memory usage when an OpenType font is downloaded as
+      # a Type 1 font.
+      # @return [Integer]
       attr_reader :max_mem_type1
 
+      # Version-specific fields.
+      # @return [TTFunk::Table::Post::Format10, TTFunk::Table::Post::Format20,
+      #   TTFunk::Table::Post::Format30, TTFunk::Table::Post::Format40]
       attr_reader :subtable
 
+      # Encode table.
+      #
+      # @param post [TTFunk::Table::Post]
+      # @param mapping [Hash{Integer => Integer}] keys are new glyph IDs, values
+      #   are old glyph IDs
+      # @return [String, nil]
       def self.encode(post, mapping)
-        return unless post.exists?
+        return if post.nil?
 
         post.recode(mapping)
       end
 
+      # Is this font monospaced?
+      #
+      # @return [Boolean]
       def fixed_pitch?
         @fixed_pitch != 0
       end
 
+      # Get glyph name for character code.
+      #
+      # This is a placeholder.
+      #
+      # @param _code [Integer]
+      # @return [String]
       def glyph_for(_code)
         '.notdef'
       end
 
+      # Re-encode this table.
+      #
+      # @param mapping [Hash{Integer => Integer}] keys are new glyph IDs, values
+      #   are old glyph IDs
+      # @return [String]
       def recode(mapping)
         return raw if format == 0x00030000
 
@@ -46,7 +106,7 @@ module TTFunk
           if position
             index << position
           else
-            index << 257 + strings.length
+            index << (257 + strings.length)
             strings << post_glyph
           end
         end
@@ -85,11 +145,7 @@ module TTFunk
       end
 
       def parse_format!
-        warn(
-          Kernel.format(
-            'postscript table format 0x%08X is not supported', @format
-          )
-        )
+        warn(Kernel.format('postscript table format 0x%08X is not supported', @format))
       end
     end
   end

data/lib/ttfunk/table/sbix.rb

@@ -4,14 +4,48 @@ require_relative '../table'
 
 module TTFunk
   class Table
+    # Standard Bitmap Graphics (`sbix`) table.
     class Sbix < Table
+      # Table version.
+      # @return [Integer]
       attr_reader :version
+
+      # Flags.
+      # @return [Integer]
       attr_reader :flags
+
+      # Number of bitmap strikes.
+      # @return [Integer]
       attr_reader :num_strikes
+
+      # Strikes.
+      # @return [Array<Hash>]
       attr_reader :strikes
 
+      # Bitmap Data.
+      #
+      # @!attribute [rw] x
+      #   The horizontal (x-axis) position of the left edge of the bitmap
+      #   graphic in relation to the glyph design space origin.
+      # @!attribute [rw] y
+      #   The vertical (y-axis) position of the bottom edge of the bitmap
+      #   graphic in relation to the glyph design space origin.
+      # @!attribute [rw] type
+      #   Indicates the format of the embedded graphic data: one of `jpg `,
+      #   `png `, `tiff`, or the special format `dupe`.
+      # @!attribute [rw] data
+      #   The actual embedded graphic data.
+      # @!attribute [rw] ppem
+      #   The PPEM size for which this strike was designed.
+      # @!attribute [rw] resolution
+      #   The device pixel density (in PPI) for which this strike was designed.
       BitmapData = Struct.new(:x, :y, :type, :data, :ppem, :resolution)
 
+      # Get bitmap for glyph strike.
+      #
+      # @param glyph_id [Integer]
+      # @param strike_index [Integer]
+      # @return [BitmapData]
       def bitmap_data_for(glyph_id, strike_index)
         strike = strikes[strike_index]
         return if strike.nil?
@@ -22,21 +56,23 @@ module TTFunk
         if glyph_offset && next_glyph_offset
           bytes = next_glyph_offset - glyph_offset
           if bytes.positive?
-            parse_from(offset + strike[:offset] + glyph_offset) do
+            parse_from(offset + strike[:offset] + glyph_offset) {
               x, y, type = read(8, 's2A4')
               data = StringIO.new(io.read(bytes - 8))
-              BitmapData.new(
-                x, y, type, data, strike[:ppem], strike[:resolution]
-              )
-            end
+              BitmapData.new(x, y, type, data, strike[:ppem], strike[:resolution])
+            }
           end
         end
       end
 
+      # Get all bitmaps for glyph.
+      #
+      # @param glyph_id [Integer]
+      # @return [Array<BitmapData>]
       def all_bitmap_data_for(glyph_id)
-        strikes.each_index.map do |strike_index|
+        strikes.each_index.filter_map { |strike_index|
           bitmap_data_for(glyph_id, strike_index)
-        end.compact
+        }
       end
 
       private
@@ -46,21 +82,21 @@ module TTFunk
         strike_offsets = Array.new(num_strikes) { read(4, 'N').first }
 
         @strikes =
-          strike_offsets.map do |strike_offset|
-            parse_from(offset + strike_offset) do
+          strike_offsets.map { |strike_offset|
+            parse_from(offset + strike_offset) {
               ppem, resolution = read(4, 'n2')
               data_offsets =
-                Array.new(file.maximum_profile.num_glyphs + 1) do
+                Array.new(file.maximum_profile.num_glyphs + 1) {
                   read(4, 'N').first
-                end
+                }
               {
                 ppem: ppem,
                 resolution: resolution,
                 offset: strike_offset,
-                glyph_data_offset: data_offsets
+                glyph_data_offset: data_offsets,
               }
-            end
-          end
+            }
+          }
       end
     end
   end

data/lib/ttfunk/table/simple.rb

@@ -4,9 +4,14 @@ require_relative '../table'
 
 module TTFunk
   class Table
+    # A table that TTFunk doesn't decode but preserve.
     class Simple < Table
+      # Table tag
+      # @return [String]
       attr_reader :tag
 
+      # @param file [TTFunk::File]
+      # @param tag [String]
       def initialize(file, tag)
         @tag = tag
         super(file)