fontisan 0.2.8 → 0.2.10

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/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