fontisan 0.1.0

data/lib/fontisan/true_type_font.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require "bindata"
+require_relative "constants"
+require_relative "utilities/checksum_calculator"
+
+module Fontisan
+  # 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.
+  #
+  # Extended from ExtractTTC to support table parsing for analysis.
+  #
+  # @example Reading and analyzing a font
+  #   ttf = TrueTypeFont.from_file("font.ttf")
+  #   puts ttf.header.num_tables  # => 14
+  #   name_table = ttf.table("name")  # Fontisan extension
+  #   puts name_table.english_name(Tables::Name::FAMILY)
+  #
+  # @example Writing a font
+  #   ttf.to_file("output.ttf")
+  class TrueTypeFont < BinData::Record
+    endian :big
+
+    offset_table :header
+    array :tables, type: :table_directory, initial_length: lambda {
+      header.num_tables
+    }
+
+    # Table data is stored separately since it's at variable offsets
+    attr_accessor :table_data
+
+    # Parsed table instances cache (Fontisan extension)
+    attr_accessor :parsed_tables
+
+    # 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.initialize_storage
+        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.initialize_storage
+      font.read_table_data(io)
+      font
+    end
+
+    # Initialize storage hashes (Fontisan extension)
+    #
+    # @return [void]
+    def initialize_storage
+      @table_data = {}
+      @parsed_tables = {}
+    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)
+        # Force UTF-8 encoding on tag for hash key consistency
+        tag_key = entry.tag.dup.force_encoding("UTF-8")
+        @table_data[tag_key] = 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
+
+    # Get list of all table tags (Fontisan extension)
+    #
+    # @return [Array<String>] Array of table tag strings
+    def table_names
+      tables.map(&:tag)
+    end
+
+    # Get parsed table instance (Fontisan extension)
+    #
+    # This method parses the raw table data into a structured table object
+    # and caches the result for subsequent calls.
+    #
+    # @param tag [String] The table tag to retrieve
+    # @return [Tables::*, nil] Parsed table object or nil if not found
+    def table(tag)
+      @parsed_tables[tag] ||= parse_table(tag)
+    end
+
+    # Get units per em from head table (Fontisan extension)
+    #
+    # @return [Integer, nil] Units per em value
+    def units_per_em
+      head = table(Constants::HEAD_TAG)
+      head&.units_per_em
+    end
+
+    private
+
+    # Parse a table from raw data (Fontisan extension)
+    #
+    # @param tag [String] The table tag to parse
+    # @return [Tables::*, nil] Parsed table object or nil
+    def parse_table(tag)
+      raw_data = @table_data[tag]
+      return nil unless raw_data
+
+      table_class = table_class_for(tag)
+      return nil unless table_class
+
+      table_class.read(raw_data)
+    end
+
+    # Map table tag to parser class (Fontisan extension)
+    #
+    # @param tag [String] The table tag
+    # @return [Class, nil] Table parser class or nil
+    def table_class_for(tag)
+      {
+        Constants::HEAD_TAG => Tables::Head,
+        Constants::NAME_TAG => Tables::Name,
+        Constants::OS2_TAG => Tables::Os2,
+        Constants::POST_TAG => Tables::Post,
+        Constants::CMAP_TAG => Tables::Cmap,
+        Constants::FVAR_TAG => Tables::Fvar,
+        Constants::GSUB_TAG => Tables::Gsub,
+        Constants::GPOS_TAG => Tables::Gpos,
+      }[tag]
+    end
+
+    # 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/fontisan/utilities/checksum_calculator.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+
+module Fontisan
+  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/fontisan/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Fontisan
+  VERSION = "0.1.0"
+end

data/lib/fontisan.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "logger"
+require "lutaml/model"
+
+# Core
+require_relative "fontisan/version"
+require_relative "fontisan/error"
+require_relative "fontisan/constants"
+
+# Binary structures and parsers
+require_relative "fontisan/parsers/tag"
+require_relative "fontisan/binary/base_record"
+
+# Table parsers
+require_relative "fontisan/tables/head"
+require_relative "fontisan/tables/name"
+require_relative "fontisan/tables/os2"
+require_relative "fontisan/tables/post"
+require_relative "fontisan/tables/cmap"
+require_relative "fontisan/tables/fvar"
+require_relative "fontisan/tables/layout_common"
+require_relative "fontisan/tables/gsub"
+require_relative "fontisan/tables/gpos"
+
+# Domain objects (BinData::Record)
+require_relative "fontisan/true_type_font"
+require_relative "fontisan/open_type_font"
+require_relative "fontisan/true_type_collection"
+require_relative "fontisan/open_type_collection"
+
+# Font loading
+require_relative "fontisan/font_loader"
+
+# Utilities
+require_relative "fontisan/utilities/checksum_calculator"
+
+# Information models (Lutaml::Model)
+require_relative "fontisan/models/font_info"
+require_relative "fontisan/models/table_info"
+require_relative "fontisan/models/glyph_info"
+require_relative "fontisan/models/unicode_mappings"
+require_relative "fontisan/models/variable_font_info"
+require_relative "fontisan/models/optical_size_info"
+require_relative "fontisan/models/scripts_info"
+require_relative "fontisan/models/features_info"
+require_relative "fontisan/models/all_scripts_features_info"
+
+# Commands
+require_relative "fontisan/commands/base_command"
+require_relative "fontisan/commands/info_command"
+require_relative "fontisan/commands/tables_command"
+require_relative "fontisan/commands/glyphs_command"
+require_relative "fontisan/commands/unicode_command"
+require_relative "fontisan/commands/variable_command"
+require_relative "fontisan/commands/optical_size_command"
+require_relative "fontisan/commands/scripts_command"
+require_relative "fontisan/commands/features_command"
+require_relative "fontisan/commands/dump_table_command"
+
+# Formatters
+require_relative "fontisan/formatters/text_formatter"
+
+# CLI
+require_relative "fontisan/cli"
+
+module Fontisan
+  class << self
+    attr_accessor :logger
+
+    def configure
+      yield self if block_given?
+    end
+  end
+
+  # Set default logger
+  self.logger = Logger.new($stdout).tap do |log|
+    log.level = Logger::WARN
+  end
+end

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: fontisan
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ribose Inc.
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-11-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bindata
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: lutaml-model
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: |
+  Fontisan provides font analysis tools and utilities. It is
+  designed as a pure Ruby implementation with full object-oriented architecture,
+  supporting extraction of information from OpenType and TrueType fonts (OTF, TTF, OTC, TTC).
+
+  The gem provides both a Ruby library API and a command-line interface,
+  with structured output formats (YAML, JSON, text).
+email:
+- open.source@ribose.com
+executables:
+- fontisan
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".rubocop_todo.yml"
+- Gemfile
+- LICENSE
+- README.adoc
+- Rakefile
+- exe/fontisan
+- fontisan.gemspec
+- lib/fontisan.rb
+- lib/fontisan/binary/base_record.rb
+- lib/fontisan/binary/structures.rb
+- lib/fontisan/cli.rb
+- lib/fontisan/commands/base_command.rb
+- lib/fontisan/commands/dump_table_command.rb
+- lib/fontisan/commands/features_command.rb
+- lib/fontisan/commands/glyphs_command.rb
+- lib/fontisan/commands/info_command.rb
+- lib/fontisan/commands/optical_size_command.rb
+- lib/fontisan/commands/scripts_command.rb
+- lib/fontisan/commands/tables_command.rb
+- lib/fontisan/commands/unicode_command.rb
+- lib/fontisan/commands/variable_command.rb
+- lib/fontisan/config/features.yml
+- lib/fontisan/config/scripts.yml
+- lib/fontisan/constants.rb
+- lib/fontisan/error.rb
+- lib/fontisan/font_loader.rb
+- lib/fontisan/formatters/text_formatter.rb
+- lib/fontisan/models/all_scripts_features_info.rb
+- lib/fontisan/models/features_info.rb
+- lib/fontisan/models/font_info.rb
+- lib/fontisan/models/glyph_info.rb
+- lib/fontisan/models/optical_size_info.rb
+- lib/fontisan/models/scripts_info.rb
+- lib/fontisan/models/table_info.rb
+- lib/fontisan/models/unicode_mappings.rb
+- lib/fontisan/models/variable_font_info.rb
+- lib/fontisan/open_type_collection.rb
+- lib/fontisan/open_type_font.rb
+- lib/fontisan/parsers/tag.rb
+- lib/fontisan/tables/cmap.rb
+- lib/fontisan/tables/fvar.rb
+- lib/fontisan/tables/gpos.rb
+- lib/fontisan/tables/gsub.rb
+- lib/fontisan/tables/head.rb
+- lib/fontisan/tables/layout_common.rb
+- lib/fontisan/tables/name.rb
+- lib/fontisan/tables/os2.rb
+- lib/fontisan/tables/post.rb
+- lib/fontisan/true_type_collection.rb
+- lib/fontisan/true_type_font.rb
+- lib/fontisan/utilities/checksum_calculator.rb
+- lib/fontisan/version.rb
+homepage: https://github.com/fontist/fontisan
+licenses:
+- BSD-2-Clause
+metadata:
+  homepage_uri: https://github.com/fontist/fontisan
+  source_code_uri: https://github.com/fontist/fontisan
+  changelog_uri: https://github.com/fontist/fontisan/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Font analysis tools and utilities for OpenType fonts
+test_files: []