extract_ttc 0.3.6 → 0.3.7

data/lib/extract_ttc/models/validation_result.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ExtractTtc
+  module Models
+    # Represents the result of a validation operation
+    #
+    # This model encapsulates the outcome of validating files, headers, or other
+    # data structures, including whether the validation passed and any error
+    # messages generated during validation.
+    #
+    # This is an immutable value object with methods to query validity status.
+    class ValidationResult
+      attr_reader :valid, :errors
+
+      # Initialize a new validation result
+      #
+      # @param valid [Boolean] Whether the validation passed
+      # @param errors [Array<String>] Array of error messages (empty if valid)
+      def initialize(valid: true, errors: [])
+        @valid = valid
+        @errors = errors.freeze
+      end
+
+      # Check if the validation passed
+      #
+      # @return [Boolean] true if valid, false otherwise
+      def valid?
+        @valid
+      end
+
+      # Check if the validation failed
+      #
+      # @return [Boolean] true if invalid, false otherwise
+      def invalid?
+        !@valid
+      end
+
+      # Add an error message to the result
+      #
+      # This creates a new ValidationResult with the error added, as the object
+      # is immutable.
+      #
+      # @param message [String] The error message to add
+      # @return [ValidationResult] A new result object with the error added
+      def add_error(message)
+        self.class.new(
+          valid: false,
+          errors: @errors.dup << message,
+        )
+      end
+    end
+  end
+end

data/lib/extract_ttc/true_type_collection.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "bindata"
+require_relative "constants"
+
+module ExtractTtc
+  # TrueType Collection domain object using BinData
+  #
+  # Represents a complete TrueType Collection file using BinData's declarative
+  # DSL for binary structure definition. The structure definition IS the
+  # documentation, and BinData handles all low-level reading/writing.
+  #
+  # @example Reading and extracting fonts
+  #   File.open("Helvetica.ttc", "rb") do |io|
+  #     ttc = TrueTypeCollection.read(io)
+  #     puts ttc.num_fonts  # => 6
+  #     fonts = ttc.extract_fonts(io)  # => [TrueTypeFont, TrueTypeFont, ...]
+  #   end
+  class TrueTypeCollection < BinData::Record
+    endian :big
+
+    string :tag, length: 4, assert: "ttcf"
+    uint16 :major_version
+    uint16 :minor_version
+    uint32 :num_fonts
+    array :font_offsets, type: :uint32, initial_length: :num_fonts
+
+    # Read TrueType Collection from a file
+    #
+    # @param path [String] Path to the TTC file
+    # @return [TrueTypeCollection] A new instance
+    # @raise [ArgumentError] if path is nil or empty
+    # @raise [Errno::ENOENT] if file does not exist
+    # @raise [RuntimeError] if file format is invalid
+    def self.from_file(path)
+      if path.nil? || path.to_s.empty?
+        raise ArgumentError,
+              "path cannot be nil or empty"
+      end
+      raise Errno::ENOENT, "File not found: #{path}" unless File.exist?(path)
+
+      File.open(path, "rb") { |io| read(io) }
+    rescue BinData::ValidityError => e
+      raise "Invalid TTC file: #{e.message}"
+    rescue EOFError => e
+      raise "Invalid TTC file: unexpected end of file - #{e.message}"
+    end
+
+    # Extract fonts as TrueTypeFont objects
+    #
+    # Reads each font from the TTC file and returns them as TrueTypeFont objects.
+    #
+    # @param io [IO] Open file handle to read fonts from
+    # @return [Array<TrueTypeFont>] Array of font objects
+    def extract_fonts(io)
+      require_relative "true_type_font"
+
+      font_offsets.map do |offset|
+        TrueTypeFont.from_ttc(io, offset)
+      end
+    end
+
+    # Validate format correctness
+    #
+    # @return [Boolean] true if the format is valid, false otherwise
+    def valid?
+      tag == Constants::TTC_TAG && num_fonts.positive? && font_offsets.length == num_fonts
+    rescue StandardError
+      false
+    end
+
+    # Get the TTC version as a single integer
+    #
+    # @return [Integer] Version number (e.g., 0x00010000 for version 1.0)
+    def version
+      (major_version << 16) | minor_version
+    end
+  end
+end

data/lib/extract_ttc/true_type_font.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require "bindata"
+require_relative "constants"
+require_relative "utilities/checksum_calculator"
+
+module ExtractTtc
+  # TTF Offset Table structure
+  class OffsetTable < BinData::Record
+    endian :big
+    uint32 :sfnt_version
+    uint16 :num_tables
+    uint16 :search_range
+    uint16 :entry_selector
+    uint16 :range_shift
+  end
+
+  # TTF Table Directory Entry structure
+  class TableDirectory < BinData::Record
+    endian :big
+    string :tag, length: 4
+    uint32 :checksum
+    uint32 :offset
+    uint32 :table_length
+  end
+
+  # TrueType Font domain object using BinData
+  #
+  # Represents a complete TrueType Font file using BinData's declarative
+  # DSL for binary structure definition. The structure definition IS the
+  # documentation, and BinData handles all low-level reading/writing.
+  #
+  # @example Writing a font
+  #   ttc = TrueTypeCollection.from_file("Helvetica.ttc")
+  #   fonts = ttc.extract_fonts
+  #   fonts[0].to_file("Helvetica_0.ttf")
+  #
+  # @example Reading a font
+  #   ttf = TrueTypeFont.from_file("font.ttf")
+  #   puts ttf.header.num_tables  # => 14
+  class TrueTypeFont < BinData::Record
+    endian :big
+
+    offset_table :header
+    array :tables, type: :table_directory, initial_length: -> {
+      header.num_tables
+    }
+
+    # Table data is stored separately since it's at variable offsets
+    attr_accessor :table_data
+
+    # Read TrueType Font from a file
+    #
+    # @param path [String] Path to the TTF file
+    # @return [TrueTypeFont] A new instance
+    # @raise [ArgumentError] if path is nil or empty
+    # @raise [Errno::ENOENT] if file does not exist
+    # @raise [RuntimeError] if file format is invalid
+    def self.from_file(path)
+      if path.nil? || path.to_s.empty?
+        raise ArgumentError,
+              "path cannot be nil or empty"
+      end
+      raise Errno::ENOENT, "File not found: #{path}" unless File.exist?(path)
+
+      File.open(path, "rb") do |io|
+        font = read(io)
+        font.read_table_data(io)
+        font
+      end
+    rescue BinData::ValidityError, EOFError => e
+      raise "Invalid TTF file: #{e.message}"
+    end
+
+    # Read TrueType Font from TTC at specific offset
+    #
+    # @param io [IO] Open file handle
+    # @param offset [Integer] Byte offset to the font
+    # @return [TrueTypeFont] A new instance
+    def self.from_ttc(io, offset)
+      io.seek(offset)
+      font = read(io)
+      font.read_table_data(io)
+      font
+    end
+
+    # Read table data for all tables
+    #
+    # @param io [IO] Open file handle
+    # @return [void]
+    def read_table_data(io)
+      @table_data = {}
+      tables.each do |entry|
+        io.seek(entry.offset)
+        @table_data[entry.tag] = io.read(entry.table_length)
+      end
+    end
+
+    # Write TrueType Font to a file
+    #
+    # Writes the complete TTF structure to disk, including proper checksum
+    # calculation and table alignment.
+    #
+    # @param path [String] Path where the TTF file will be written
+    # @return [Integer] Number of bytes written
+    # @raise [IOError] if writing fails
+    def to_file(path)
+      File.open(path, "wb") do |io|
+        # Write header and tables (directory)
+        write_structure(io)
+
+        # Write table data with updated offsets
+        write_table_data_with_offsets(io)
+
+        io.pos
+      end
+
+      # Update checksum adjustment in head table
+      update_checksum_adjustment_in_file(path) if head_table
+
+      File.size(path)
+    end
+
+    # Validate format correctness
+    #
+    # @return [Boolean] true if the TTF format is valid, false otherwise
+    def valid?
+      return false unless header
+      return false unless tables.respond_to?(:length)
+      return false unless @table_data.is_a?(Hash)
+      return false if tables.length != header.num_tables
+      return false unless head_table
+
+      true
+    end
+
+    # Check if font has a specific table
+    #
+    # @param tag [String] The table tag to check for
+    # @return [Boolean] true if table exists, false otherwise
+    def has_table?(tag)
+      tables.any? { |entry| entry.tag == tag }
+    end
+
+    # Find a table entry by tag
+    #
+    # @param tag [String] The table tag to find
+    # @return [TableDirectory, nil] The table entry or nil
+    def find_table_entry(tag)
+      tables.find { |entry| entry.tag == tag }
+    end
+
+    # Get the head table entry
+    #
+    # @return [TableDirectory, nil] The head table entry or nil
+    def head_table
+      find_table_entry(Constants::HEAD_TAG)
+    end
+
+    private
+
+    # Write the structure (header + table directory) to IO
+    #
+    # @param io [IO] Open file handle
+    # @return [void]
+    def write_structure(io)
+      # Write header
+      header.write(io)
+
+      # Write table directory with placeholder offsets
+      tables.each do |entry|
+        io.write(entry.tag)
+        io.write([entry.checksum].pack("N"))
+        io.write([0].pack("N")) # Placeholder offset
+        io.write([entry.table_length].pack("N"))
+      end
+    end
+
+    # Write table data and update offsets in directory
+    #
+    # @param io [IO] Open file handle
+    # @return [void]
+    def write_table_data_with_offsets(io)
+      tables.each_with_index do |entry, index|
+        # Record current position
+        current_position = io.pos
+
+        # Write table data
+        data = @table_data[entry.tag]
+        raise IOError, "Missing table data for tag '#{entry.tag}'" if data.nil?
+
+        io.write(data)
+
+        # Add padding to align to 4-byte boundary
+        padding = (Constants::TABLE_ALIGNMENT - (io.pos % Constants::TABLE_ALIGNMENT)) % Constants::TABLE_ALIGNMENT
+        io.write("\x00" * padding) if padding.positive?
+
+        # Zero out checksumAdjustment field in head table
+        if entry.tag == Constants::HEAD_TAG
+          current_pos = io.pos
+          io.seek(current_position + 8)
+          io.write([0].pack("N"))
+          io.seek(current_pos)
+        end
+
+        # Update offset in table directory
+        # Table directory starts at byte 12, each entry is 16 bytes
+        # Offset field is at byte 8 within each entry
+        directory_offset_position = 12 + (index * 16) + 8
+        current_pos = io.pos
+        io.seek(directory_offset_position)
+        io.write([current_position].pack("N"))
+        io.seek(current_pos)
+      end
+    end
+
+    # Update checksumAdjustment field in head table
+    #
+    # @param path [String] Path to the TTF file
+    # @return [void]
+    def update_checksum_adjustment_in_file(path)
+      # Calculate file checksum
+      checksum = Utilities::ChecksumCalculator.calculate_file_checksum(path)
+
+      # Calculate adjustment
+      adjustment = Utilities::ChecksumCalculator.calculate_adjustment(checksum)
+
+      # Find head table position
+      head_entry = head_table
+      return unless head_entry
+
+      # Write adjustment to head table (offset 8 within head table)
+      File.open(path, "r+b") do |io|
+        io.seek(head_entry.offset + 8)
+        io.write([adjustment].pack("N"))
+      end
+    end
+  end
+end

data/lib/extract_ttc/utilities/checksum_calculator.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+
+module ExtractTtc
+  module Utilities
+    # ChecksumCalculator provides stateless utility methods for calculating font file checksums.
+    #
+    # This class implements the TrueType/OpenType checksum algorithm which sums all uint32
+    # values in a file. The checksum is used to verify file integrity and calculate the
+    # checksumAdjustment value stored in the 'head' table.
+    #
+    # @example Calculate file checksum
+    #   checksum = ChecksumCalculator.calculate_file_checksum("font.ttf")
+    #   # => 2842116234
+    #
+    # @example Calculate checksum adjustment
+    #   adjustment = ChecksumCalculator.calculate_adjustment(checksum)
+    #   # => 1452851062
+    class ChecksumCalculator
+      # Calculate the checksum of an entire font file.
+      #
+      # The checksum is calculated by summing all uint32 (4-byte) values in the file.
+      # Files that are not multiples of 4 bytes are padded with zeros. The sum is
+      # masked to 32 bits to prevent overflow.
+      #
+      # @param file_path [String] path to the font file
+      # @return [Integer] the calculated uint32 checksum
+      # @raise [Errno::ENOENT] if the file does not exist
+      # @raise [Errno::EACCES] if the file cannot be read
+      #
+      # @example
+      #   checksum = ChecksumCalculator.calculate_file_checksum("font.ttf")
+      #   # => 2842116234
+      def self.calculate_file_checksum(file_path)
+        File.open(file_path, "rb") do |file|
+          calculate_checksum_from_io(file)
+        end
+      end
+
+      # Calculate the checksum adjustment value for the 'head' table.
+      #
+      # The checksum adjustment is stored at offset 8 in the 'head' table and is
+      # calculated as: CHECKSUM_ADJUSTMENT_MAGIC - file_checksum.
+      # This value ensures that the checksum of the entire font file equals the
+      # magic number.
+      #
+      # @param file_checksum [Integer] the calculated file checksum
+      # @return [Integer] the checksum adjustment value to write to the 'head' table
+      #
+      # @example
+      #   adjustment = ChecksumCalculator.calculate_adjustment(2842116234)
+      #   # => 1452851062
+      def self.calculate_adjustment(file_checksum)
+        (Constants::CHECKSUM_ADJUSTMENT_MAGIC - file_checksum) & 0xFFFFFFFF
+      end
+
+      # Calculate checksum from an IO object.
+      #
+      # Reads the IO stream in 4-byte chunks and calculates the uint32 checksum.
+      # This is the core checksum algorithm implementation.
+      #
+      # @param io [IO] the IO object to read from
+      # @return [Integer] the calculated uint32 checksum
+      # @api private
+      def self.calculate_checksum_from_io(io)
+        io.rewind
+        sum = 0
+
+        until io.eof?
+          # Read 4 bytes at a time
+          bytes = io.read(4)
+          break if bytes.nil? || bytes.empty?
+
+          # Pad with zeros if less than 4 bytes
+          bytes += "\0" * (4 - bytes.length) if bytes.length < 4
+
+          # Convert to uint32 (network byte order, big-endian)
+          value = bytes.unpack1("N")
+          sum = (sum + value) & 0xFFFFFFFF
+        end
+
+        sum
+      end
+
+      private_class_method :calculate_checksum_from_io
+    end
+  end
+end

data/lib/extract_ttc/utilities/output_path_generator.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module ExtractTtc
+  module Utilities
+    # OutputPathGenerator provides stateless utility methods for generating output file paths.
+    #
+    # This class generates standardized output paths for extracted TTF files from TTC files,
+    # using a consistent naming convention with zero-padded indices.
+    #
+    # @example Generate output path with defaults
+    #   path = OutputPathGenerator.generate("Helvetica.ttc", 0)
+    #   # => "Helvetica_00.ttf"
+    #
+    # @example Generate output path with custom directory
+    #   path = OutputPathGenerator.generate("Helvetica.ttc", 5, output_dir: "/tmp/fonts")
+    #   # => "/tmp/fonts/Helvetica_05.ttf"
+    class OutputPathGenerator
+      # Default format string for zero-padded font indices.
+      # Produces two-digit indices (00, 01, 02, etc.)
+      DEFAULT_INDEX_FORMAT = "%02d"
+
+      # Generate an output TTF file path for an extracted font.
+      #
+      # The output path is constructed from the input file's basename, a zero-padded
+      # font index, and an optional output directory. The resulting filename follows
+      # the pattern: "basename_XX.ttf" where XX is the zero-padded index.
+      #
+      # @param input_path [String] path to the input TTC file
+      # @param font_index [Integer] zero-based index of the font being extracted
+      # @param output_dir [String, nil] optional output directory (defaults to current directory ".")
+      # @return [String] the generated output file path
+      # @raise [ArgumentError] if font_index is negative
+      #
+      # @example Generate path in current directory
+      #   OutputPathGenerator.generate("fonts/Helvetica.ttc", 0)
+      #   # => "Helvetica_00.ttf"
+      #
+      # @example Generate path in specific directory
+      #   OutputPathGenerator.generate("Helvetica.ttc", 3, output_dir: "/tmp")
+      #   # => "/tmp/Helvetica_03.ttf"
+      #
+      # @example High font index
+      #   OutputPathGenerator.generate("Font.ttc", 15)
+      #   # => "Font_15.ttf"
+      def self.generate(input_path, font_index, output_dir: nil)
+        if font_index.negative?
+          raise ArgumentError,
+                "font_index must be non-negative"
+        end
+
+        basename = File.basename(input_path, ".*")
+        formatted_index = sprintf(DEFAULT_INDEX_FORMAT, font_index)
+        filename = "#{basename}_#{formatted_index}.ttf"
+
+        if output_dir.nil? || output_dir.empty? || output_dir == "."
+          filename
+        else
+          File.join(output_dir, filename)
+        end
+      end
+
+      # Generate output path with a custom index format.
+      #
+      # Allows specifying a custom sprintf format string for the index padding,
+      # enabling different padding widths or styles.
+      #
+      # @param input_path [String] path to the input TTC file
+      # @param font_index [Integer] zero-based index of the font being extracted
+      # @param index_format [String] sprintf format string for index formatting
+      # @param output_dir [String, nil] optional output directory
+      # @return [String] the generated output file path
+      # @raise [ArgumentError] if font_index is negative
+      #
+      # @example Three-digit padding
+      #   OutputPathGenerator.generate_with_format("Font.ttc", 5, "%03d")
+      #   # => "Font_005.ttf"
+      #
+      # @example No padding
+      #   OutputPathGenerator.generate_with_format("Font.ttc", 5, "%d")
+      #   # => "Font_5.ttf"
+      def self.generate_with_format(input_path, font_index, index_format,
+output_dir: nil)
+        if font_index.negative?
+          raise ArgumentError,
+                "font_index must be non-negative"
+        end
+
+        basename = File.basename(input_path, ".*")
+        formatted_index = sprintf(index_format, font_index)
+        filename = "#{basename}_#{formatted_index}.ttf"
+
+        if output_dir.nil? || output_dir.empty?
+          filename
+        else
+          File.join(output_dir, filename)
+        end
+      end
+    end
+  end
+end

data/lib/extract_ttc/version.rb

@@ -1,3 +1,3 @@
 module ExtractTtc
-  VERSION = "0.3.6".freeze
+  VERSION = "0.3.7".freeze
 end