fontisan 0.2.7 → 0.2.9

data/lib/fontisan/sfnt_table.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+require_relative "loading_modes"
+
+module Fontisan
+  # Base class for SFNT font tables
+  #
+  # Represents a single table in an SFNT font file, encapsulating:
+  # - Table metadata (tag, checksum, offset, length)
+  # - Lazy loading of table data
+  # - Parsing of table data into structured objects
+  # - Table-specific validation
+  #
+  # This class provides an OOP representation of font tables, replacing
+  # the previous separation of TableDirectory (metadata), @table_data (raw bytes),
+  # and @parsed_tables (parsed objects) with a single cohesive domain object.
+  #
+  # @abstract Subclasses should override `parser_class` and `validate_parsed_table?`
+  #
+  # @example Accessing table metadata
+  #   table = SfntTable.new(font, entry)
+  #   puts table.tag        # => "head"
+  #   puts table.checksum   # => 0x12345678
+  #   puts table.offset     # => 0x0000012C
+  #   puts table.length     # => 54
+  #
+  # @example Lazy loading table data
+  #   table.load_data!  # Loads raw bytes from IO
+  #   puts table.data.bytesize
+  #
+  # @example Parsing table data
+  #   head_table = table.parse
+  #   puts head_table.units_per_em
+  #
+  # @example Validating table
+  #   table.validate!  # Raises InvalidFontError if invalid
+  class SfntTable
+    # Table metadata entry (from TableDirectory)
+    #
+    # @return [TableDirectory] The table directory entry
+    attr_reader :entry
+
+    # Parent font containing this table
+    #
+    # @return [SfntFont] The font that contains this table
+    attr_reader :font
+
+    # Raw table data (loaded lazily)
+    #
+    # @return [String, nil] Raw binary table data, or nil if not loaded
+    attr_reader :data
+
+    # Parsed table object (cached)
+    #
+    # @return [Object, nil] Parsed table object, or nil if not parsed
+    attr_reader :parsed
+
+    # Table tag (4-character string)
+    #
+    # @return [String] The table tag (e.g., "head", "name", "cmap")
+    def tag
+      @entry.tag
+    end
+
+    # Table checksum
+    #
+    # @return [Integer] The table checksum
+    def checksum
+      @entry.checksum
+    end
+
+    # Table offset in font file
+    #
+    # @return [Integer] Byte offset of table data
+    def offset
+      @entry.offset
+    end
+
+    # Table length in bytes
+    #
+    # @return [Integer] Table data length in bytes
+    def length
+      @entry.table_length
+    end
+
+    # Initialize a new SfntTable
+    #
+    # @param font [SfntFont] The font containing this table
+    # @param entry [TableDirectory] The table directory entry
+    def initialize(font, entry)
+      @font = font
+      @entry = entry
+      @data = nil
+      @parsed = nil
+    end
+
+    # Load raw table data from font file
+    #
+    # Reads the table data from the font's IO source or from cached
+    # table data. This method supports lazy loading.
+    #
+    # @return [self] Returns self for chaining
+    # @raise [RuntimeError] if table data cannot be loaded
+    def load_data!
+      # Check if already loaded
+      return self if @data
+
+      # Try to get from font's table_data cache
+      if @font.table_data && @font.table_data[tag]
+        @data = @font.table_data[tag]
+        return self
+      end
+
+      # Load from IO source if available
+      if @font.io_source
+        @font.io_source.seek(offset)
+        @data = @font.io_source.read(length)
+        return self
+      end
+
+      raise "Cannot load table '#{tag}': no IO source or cached data"
+    end
+
+    # Check if table data is loaded
+    #
+    # @return [Boolean] true if table data has been loaded
+    def data_loaded?
+      !@data.nil?
+    end
+
+    # Check if table has been parsed
+    #
+    # @return [Boolean] true if table has been parsed
+    def parsed?
+      !@parsed.nil?
+    end
+
+    # Parse table data into structured object
+    #
+    # Loads data if needed, then parses using the table-specific parser class.
+    # Results are cached for subsequent calls.
+    #
+    # @return [Object, nil] Parsed table object, or nil if no parser available
+    # @raise [RuntimeError] if table data cannot be loaded for parsing
+    def parse
+      return @parsed if parsed?
+
+      # Load data if not already loaded
+      load_data! unless data_loaded?
+
+      # Get parser class for this table type
+      parser = parser_class
+      return nil unless parser
+
+      # Parse and cache
+      @parsed = parser.read(@data)
+      @parsed
+    end
+
+    # Validate the table
+    #
+    # Performs table-specific validation. Subclasses should override
+    # `validate_parsed_table?` to provide custom validation logic.
+    #
+    # @return [Boolean] true if table is valid
+    # @raise [Fontisan::InvalidFontError] if table is invalid
+    def validate!
+      # Ensure data is loaded
+      load_data! unless data_loaded?
+
+      # Basic validation: data size matches expected size
+      if @data.bytesize != length
+        raise InvalidFontError,
+              "Table '#{tag}' data size mismatch: expected #{length} bytes, got #{@data.bytesize}"
+      end
+
+      # Validate checksum if not head table (head table checksum is special)
+      if tag != Constants::HEAD_TAG
+        expected_checksum = calculate_checksum
+        if checksum != expected_checksum
+          # Checksum mismatch might be OK for some tables, log a warning
+          # But don't fail validation for it
+        end
+      end
+
+      # Table-specific validation (if parsed)
+      if parsed?
+        validate_parsed_table?
+      end
+
+      true
+    end
+
+    # Calculate table checksum
+    #
+    # @return [Integer] The checksum of the table data
+    def calculate_checksum
+      load_data! unless data_loaded?
+
+      require_relative "utilities/checksum_calculator"
+      Utilities::ChecksumCalculator.calculate_table_checksum(@data)
+    end
+
+    # Check if table is available in current loading mode
+    #
+    # @return [Boolean] true if table is available
+    def available?
+      @font.table_available?(tag)
+    end
+
+    # Check if table is required for the font
+    #
+    # @return [Boolean] true if table is required
+    def required?
+      Constants::REQUIRED_TABLES.include?(tag)
+    end
+
+    # Get human-readable table name
+    #
+    # @return [String] Human-readable name
+    def human_name
+      Constants::TABLE_NAMES[tag] || tag
+    end
+
+    # String representation
+    #
+    # @return [String] Human-readable representation
+    def inspect
+      "#<#{self.class.name} tag=#{tag.inspect} offset=0x#{offset.to_s(16).upcase} length=#{length}>"
+    end
+
+    # String representation for display
+    #
+    # @return [String] Human-readable representation
+    def to_s
+      "#{tag}: #{human_name} (#{length} bytes @ 0x#{offset.to_s(16).upcase})"
+    end
+
+    protected
+
+    # Get the parser class for this table type
+    #
+    # Subclasses should override this method to return the appropriate
+    # Tables::* class (e.g., Tables::Head, Tables::Name).
+    #
+    # @return [Class, nil] The parser class, or nil if no parser available
+    def parser_class
+      # Direct access to TABLE_CLASS_MAP for better performance
+      @font.class::TABLE_CLASS_MAP[tag]
+    end
+
+    # Validate the parsed table object
+    #
+    # Subclasses should override this method to provide table-specific
+    # validation logic. The default implementation does nothing.
+    #
+    # @return [Boolean] true if valid
+    # @raise [Fontisan::InvalidFontError] if table is invalid
+    def validate_parsed_table?
+      true
+    end
+  end
+end

data/lib/fontisan/subset/glyph_mapping.rb

@@ -30,6 +30,8 @@ module Fontisan
     #   mapping = Fontisan::Subset::GlyphMapping.new([0, 5, 10])
     #   mapping.old_id(1) # => 5
     class GlyphMapping
+      include Enumerable
+
       # @return [Hash<Integer, Integer>] mapping from old GIDs to new GIDs
       attr_reader :old_to_new
 

data/lib/fontisan/subset/table_subsetter.rb

@@ -152,7 +152,7 @@ module Fontisan
         # Build new hmtx data
         data = String.new(encoding: Encoding::BINARY)
 
-        mapping.each do |old_id, _new_id|
+        mapping.old_ids.each do |old_id|
           metric = table.metric_for(old_id)
           next unless metric
 
@@ -319,7 +319,7 @@ module Fontisan
         current_offset = 0
 
         # Process glyphs in mapping order
-        mapping.each do |old_id, _new_id|
+        mapping.old_ids.each do |old_id|
           @loca_offsets << current_offset
 
           # Get offset and size from original loca

data/lib/fontisan/tables/cblc.rb

@@ -86,9 +86,12 @@ module Fontisan
           size = new
 
           io = StringIO.new(data)
-          size.instance_variable_set(:@index_subtable_array_offset, io.read(4).unpack1("N"))
-          size.instance_variable_set(:@index_tables_size, io.read(4).unpack1("N"))
-          size.instance_variable_set(:@number_of_index_subtables, io.read(4).unpack1("N"))
+          size.instance_variable_set(:@index_subtable_array_offset,
+                                     io.read(4).unpack1("N"))
+          size.instance_variable_set(:@index_tables_size,
+                                     io.read(4).unpack1("N"))
+          size.instance_variable_set(:@number_of_index_subtables,
+                                     io.read(4).unpack1("N"))
           size.instance_variable_set(:@color_ref, io.read(4).unpack1("N"))
 
           # Parse hori and vert metrics (12 bytes each)
@@ -98,7 +101,8 @@ module Fontisan
           size.instance_variable_set(:@vert, SbitLineMetrics.read(vert_data))
 
           # Parse remaining fields
-          size.instance_variable_set(:@start_glyph_index, io.read(2).unpack1("n"))
+          size.instance_variable_set(:@start_glyph_index,
+                                     io.read(2).unpack1("n"))
           size.instance_variable_set(:@end_glyph_index, io.read(2).unpack1("n"))
           size.instance_variable_set(:@ppem_x, io.read(1).unpack1("C"))
           size.instance_variable_set(:@ppem_y, io.read(1).unpack1("C"))

data/lib/fontisan/tables/cff/index.rb

@@ -35,6 +35,8 @@ module Fontisan
       #   puts index[0]  # => first item data
       #   index.each { |item| puts item }
       class Index
+        include Enumerable
+
         # @return [Integer] Number of items in the INDEX
         attr_reader :count
 

data/lib/fontisan/tables/cff.rb

@@ -299,7 +299,8 @@ module Fontisan
         io.seek(absolute_offset)
         Index.new(io, start_offset: absolute_offset)
       rescue StandardError => e
-        raise CorruptedTableError, "Failed to parse Local Subr INDEX: #{e.message}"
+        raise CorruptedTableError,
+              "Failed to parse Local Subr INDEX: #{e.message}"
       end
 
       # Get the CharStrings INDEX for a specific font
@@ -320,7 +321,8 @@ module Fontisan
         io.seek(charstrings_offset)
         CharstringsIndex.new(io, start_offset: charstrings_offset)
       rescue StandardError => e
-        raise CorruptedTableError, "Failed to parse CharStrings INDEX: #{e.message}"
+        raise CorruptedTableError,
+              "Failed to parse CharStrings INDEX: #{e.message}"
       end
 
       # Get a CharString for a specific glyph
@@ -355,7 +357,8 @@ module Fontisan
           local_subr_index,
         )
       rescue StandardError => e
-        raise CorruptedTableError, "Failed to get CharString for glyph #{glyph_index}: #{e.message}"
+        raise CorruptedTableError,
+              "Failed to get CharString for glyph #{glyph_index}: #{e.message}"
       end
 
       # Get the number of glyphs in a font

data/lib/fontisan/tables/cff2/private_dict_blend_handler.rb

@@ -51,7 +51,7 @@ module Fontisan
           # Check if this is blend data
           # Format: base1 delta1_1 ... delta1_N base2 delta2_1 ... delta2_N ...
           # The array must be divisible by (num_axes + 1)
-          return nil unless value.size % (num_axes + 1) == 0
+          return nil unless (value.size % (num_axes + 1)).zero?
 
           num_values = value.size / (num_axes + 1)
           blends = []

data/lib/fontisan/tables/cff2.rb

@@ -121,7 +121,7 @@ module Fontisan
       def charstrings
         return [] unless @charstrings_index
 
-        @charstrings_index.count.times.map do |glyph_id|
+        Array.new(@charstrings_index.count) do |glyph_id|
           charstring_for_glyph(glyph_id)
         end.compact
       end

data/lib/fontisan/tables/cmap.rb

@@ -278,22 +278,20 @@ module Fontisan
         end
       end
 
-      public
-
       # Validation helper: Check if version is valid
       #
       # cmap version should be 0
       #
       # @return [Boolean] True if version is 0
       def valid_version?
-        version == 0
+        version.zero?
       end
 
       # Validation helper: Check if at least one subtable exists
       #
       # @return [Boolean] True if num_tables > 0
       def has_subtables?
-        num_tables && num_tables > 0
+        num_tables&.positive?
       end
 
       # Validation helper: Check if Unicode mapping exists
@@ -357,7 +355,9 @@ module Fontisan
         mappings = unicode_mappings
         return true if mappings.nil? || mappings.empty?
 
-        mappings.values.all? { |glyph_id| glyph_id >= 0 && glyph_id < max_glyph_id }
+        mappings.values.all? do |glyph_id|
+          glyph_id >= 0 && glyph_id < max_glyph_id
+        end
       end
     end
   end

data/lib/fontisan/tables/cmap_table.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require_relative "../sfnt_table"
+require_relative "cmap"
+
+module Fontisan
+  module Tables
+    # OOP representation of the 'cmap' (Character to Glyph Index Mapping) table
+    #
+    # The cmap table maps character codes to glyph indices, supporting multiple
+    # encoding formats for different character sets and Unicode planes.
+    #
+    # This class extends SfntTable to provide cmap-specific validation and
+    # convenience methods for character-to-glyph mapping.
+    #
+    # @example Mapping characters to glyphs
+    #   cmap = font.sfnt_table("cmap")
+    #   cmap.glyph_for('A')        # => 36
+    #   cmap.glyph_for(0x0041)     # => 36 (same as 'A')
+    #   cmap.has_glyph?('€')       # => true
+    #   cmap.character_count       # => 1234
+    class CmapTable < SfntTable
+      # Get Unicode character to glyph index mappings
+      #
+      # @return [Hash<Integer, Integer>] Mapping from Unicode codepoints to glyph IDs
+      def unicode_mappings
+        return {} unless parsed
+
+        parsed.unicode_mappings || {}
+      end
+
+      # Get glyph ID for a character
+      #
+      # @param char [String, Integer] Character (string or Unicode codepoint)
+      # @return [Integer, nil] Glyph ID, or nil if character not mapped
+      def glyph_for(char)
+        codepoint = char.is_a?(String) ? char.ord : char
+        unicode_mappings[codepoint]
+      end
+
+      # Check if a character has a glyph mapping
+      #
+      # @param char [String, Integer] Character (string or Unicode codepoint)
+      # @return [Boolean] true if character is mapped to a glyph
+      def has_glyph?(char)
+        !glyph_for(char).nil?
+      end
+
+      # Check if multiple characters have glyph mappings
+      #
+      # @param chars [Array<String, Integer>] Characters to check
+      # @return [Boolean] true if all characters are mapped
+      def has_glyphs?(*chars)
+        chars.all? { |char| has_glyph?(char) }
+      end
+
+      # Get the number of mapped characters
+      #
+      # @return [Integer] Number of unique character mappings
+      def character_count
+        unicode_mappings.size
+      end
+
+      # Get all mapped character codes
+      #
+      # @return [Array<Integer>] Array of Unicode codepoints
+      def character_codes
+        unicode_mappings.keys.sort
+      end
+
+      # Get all mapped glyphs
+      #
+      # @return [Array<Integer>] Array of glyph IDs
+      def glyph_ids
+        unicode_mappings.values.uniq.sort
+      end
+
+      # Check if BMP (Basic Multilingual Plane) coverage exists
+      #
+      # @return [Boolean] true if BMP characters (U+0000-U+FFFF) are mapped
+      def has_bmp_coverage?
+        return false unless parsed
+
+        parsed.has_bmp_coverage?
+      end
+
+      # Check if specific required characters are mapped
+      #
+      # @param chars [Array<Integer>] Unicode codepoints that must be present
+      # @return [Boolean] true if all required characters are mapped
+      def has_required_characters?(*chars)
+        return false unless parsed
+
+        parsed.has_required_characters?(*chars)
+      end
+
+      # Check if space character is mapped
+      #
+      # @return [Boolean] true if U+0020 (space) is mapped
+      def has_space?
+        has_glyph?(0x0020)
+      end
+
+      # Check if common Latin characters are mapped
+      #
+      # @return [Boolean] true if A-Z, a-z are mapped
+      def has_basic_latin?
+        # Check uppercase A-Z
+        return false unless has_glyphs?(*(0x0041..0x005A).to_a)
+
+        # Check lowercase a-z
+        has_glyphs?(*(0x0061..0x007A).to_a)
+      end
+
+      # Check if digits are mapped
+      #
+      # @return [Boolean] true if 0-9 are mapped
+      def has_digits?
+        has_glyphs?(*(0x0030..0x0039).to_a)
+      end
+
+      # Check if common punctuation is mapped
+      #
+      # @return [Boolean] true if common punctuation marks are mapped
+      def has_basic_punctuation?
+        required = [0x0020, 0x0021, 0x0022, 0x0027, 0x0028, 0x0029, 0x002C, 0x002E,
+                    0x003A, 0x003B, 0x003F, 0x005F] # space !"()',.:;?_
+        has_required_characters?(*required)
+      end
+
+      # Get glyph IDs for a string of characters
+      #
+      # @param text [String] Text string
+      # @return [Array<Integer>] Array of glyph IDs
+      def glyphs_for_text(text)
+        text.chars.map { |char| glyph_for(char) || 0 }
+      end
+
+      # Create a simple text rendering glyph sequence
+      #
+      # @param text [String] Text string
+      # @return [Array<Integer>] Array of glyph IDs for rendering
+      def glyph_sequence_for(text)
+        glyphs_for_text(text)
+      end
+
+      # Get the highest Unicode codepoint mapped
+      #
+      # @return [Integer, nil] Maximum codepoint, or nil if no mappings
+      def max_codepoint
+        codes = character_codes
+        codes.last unless codes.empty?
+      end
+
+      # Get the lowest Unicode codepoint mapped
+      #
+      # @return [Integer, nil] Minimum codepoint, or nil if no mappings
+      def min_codepoint
+        codes = character_codes
+        codes.first unless codes.empty?
+      end
+
+      # Check if font has full Unicode coverage
+      #
+      # @return [Boolean] true if characters beyond BMP are mapped
+      def has_full_unicode?
+        max_cp = max_codepoint
+        !max_cp.nil? && max_cp > 0xFFFF
+      end
+
+      # Get mapping statistics
+      #
+      # @return [Hash] Statistics about the character mapping
+      def statistics
+        {
+          character_count: character_count,
+          glyph_count: glyph_ids.size,
+          min_codepoint: min_codepoint,
+          max_codepoint: max_codepoint,
+          has_bmp: has_bmp_coverage?,
+          has_full_unicode: has_full_unicode?,
+          has_space: has_space?,
+          has_basic_latin: has_basic_latin?,
+          has_digits: has_digits?,
+        }
+      end
+
+      protected
+
+      # Validate the parsed cmap table
+      #
+      # @return [Boolean] true if valid
+      # @raise [InvalidFontError] if cmap table is invalid
+      def validate_parsed_table?
+        return true unless parsed
+
+        # Validate version
+        unless parsed.valid_version?
+          raise InvalidFontError,
+                "Invalid cmap table version: #{parsed.version} (must be 0)"
+        end
+
+        # Validate subtables exist
+        unless parsed.has_subtables?
+          raise InvalidFontError,
+                "Invalid cmap table: no subtables found (num_tables=#{parsed.num_tables})"
+        end
+
+        # Validate Unicode mapping exists
+        unless parsed.has_unicode_mapping?
+          raise InvalidFontError,
+                "Invalid cmap table: no Unicode mappings found"
+        end
+
+        # Validate BMP coverage (required for fonts)
+        unless parsed.has_bmp_coverage?
+          raise InvalidFontError,
+                "Invalid cmap table: no BMP character coverage found"
+        end
+
+        # Validate required characters (space at minimum)
+        unless parsed.has_required_characters?(0x0020)
+          raise InvalidFontError,
+                "Invalid cmap table: missing required character U+0020 (space)"
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/fontisan/tables/glyf.rb

@@ -166,7 +166,7 @@ module Fontisan
       # @param head [Head] Head table for context
       # @param num_glyphs [Integer] Total number of glyphs to check
       # @return [Boolean] True if all non-special glyphs have contours
-      def no_empty_glyphs_except_special?(loca, head, num_glyphs)
+      def no_empty_glyphs_except_special?(loca, _head, num_glyphs)
         # Check glyphs 1 through num_glyphs-1 (.notdef at 0 can be empty)
         (1...num_glyphs).all? do |glyph_id|
           size = loca.size_of(glyph_id)
@@ -194,7 +194,7 @@ module Fontisan
 
         (0...num_glyphs).all? do |glyph_id|
           glyph = glyph_for(glyph_id, loca, head)
-          next true if glyph.nil?  # Empty glyphs are OK
+          next true if glyph.nil? # Empty glyphs are OK
 
           # Check if glyph bounds are within font bounds
           glyph.x_min >= font_x_min &&
@@ -218,7 +218,7 @@ module Fontisan
       def instructions_sound?(loca, head, num_glyphs)
         (0...num_glyphs).all? do |glyph_id|
           glyph = glyph_for(glyph_id, loca, head)
-          next true if glyph.nil?  # Empty glyphs are OK
+          next true if glyph.nil? # Empty glyphs are OK
 
           # Simple glyphs have instructions
           if glyph.respond_to?(:instruction_length)
@@ -242,7 +242,7 @@ module Fontisan
       # @return [Boolean] True if contour count is valid
       def valid_contour_count?(glyph_id, loca, head)
         glyph = glyph_for(glyph_id, loca, head)
-        return true if glyph.nil?  # Empty glyphs are OK
+        return true if glyph.nil? # Empty glyphs are OK
 
         # Simple glyphs: contours should be >= 0
         # Compound glyphs: numberOfContours = -1
@@ -265,12 +265,10 @@ module Fontisan
       # @return [Boolean] True if all glyphs can be accessed
       def all_glyphs_accessible?(loca, head, num_glyphs)
         (0...num_glyphs).all? do |glyph_id|
-          begin
-            glyph_for(glyph_id, loca, head)
-            true
-          rescue Fontisan::CorruptedTableError
-            false
-          end
+          glyph_for(glyph_id, loca, head)
+          true
+        rescue Fontisan::CorruptedTableError
+          false
         end
       rescue StandardError
         false