fontisan 0.1.0 → 0.2.0

data/lib/fontisan/true_type_font.rb

@@ -2,6 +2,7 @@
 
 require "bindata"
 require_relative "constants"
+require_relative "loading_modes"
 require_relative "utilities/checksum_calculator"
 
 module Fontisan
@@ -38,6 +39,11 @@ module Fontisan
   #   name_table = ttf.table("name")  # Fontisan extension
   #   puts name_table.english_name(Tables::Name::FAMILY)
   #
+  # @example Loading with metadata mode
+  #   ttf = TrueTypeFont.from_file("font.ttf", mode: :metadata)
+  #   puts ttf.loading_mode  # => :metadata
+  #   ttf.table_available?("GSUB")  # => false
+  #
   # @example Writing a font
   #   ttf.to_file("output.ttf")
   class TrueTypeFont < BinData::Record
@@ -54,24 +60,55 @@ module Fontisan
     # Parsed table instances cache (Fontisan extension)
     attr_accessor :parsed_tables
 
+    # Loading mode for this font (:metadata or :full)
+    attr_accessor :loading_mode
+
+    # IO source for lazy loading
+    attr_accessor :io_source
+
+    # Whether lazy loading is enabled
+    attr_accessor :lazy_load_enabled
+
+    # Page cache for lazy loading (maps page_start_offset => page_data)
+    attr_accessor :page_cache
+
+    # Page size for lazy loading alignment (typical filesystem page size)
+    PAGE_SIZE = 4096
+
     # Read TrueType Font from a file
     #
     # @param path [String] Path to the TTF file
+    # @param mode [Symbol] Loading mode (:metadata or :full, default: :full)
+    # @param lazy [Boolean] If true, load tables on demand (default: false for eager loading)
     # @return [TrueTypeFont] A new instance
-    # @raise [ArgumentError] if path is nil or empty
+    # @raise [ArgumentError] if path is nil or empty, or if mode is invalid
     # @raise [Errno::ENOENT] if file does not exist
     # @raise [RuntimeError] if file format is invalid
-    def self.from_file(path)
+    def self.from_file(path, mode: LoadingModes::FULL, lazy: false)
       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)
 
+      # Validate mode
+      LoadingModes.validate_mode!(mode)
+
       File.open(path, "rb") do |io|
         font = read(io)
         font.initialize_storage
-        font.read_table_data(io)
+        font.loading_mode = mode
+        font.lazy_load_enabled = lazy
+
+        if lazy
+          # Keep file handle open for lazy loading
+          font.io_source = File.open(path, "rb")
+          font.setup_finalizer
+        else
+          # Read tables upfront
+          font.read_table_data(io)
+        end
+
         font
       end
     rescue BinData::ValidityError, EOFError => e
@@ -82,11 +119,15 @@ module Fontisan
     #
     # @param io [IO] Open file handle
     # @param offset [Integer] Byte offset to the font
+    # @param mode [Symbol] Loading mode (:metadata or :full, default: :full)
     # @return [TrueTypeFont] A new instance
-    def self.from_ttc(io, offset)
+    def self.from_ttc(io, offset, mode: LoadingModes::FULL)
+      LoadingModes.validate_mode!(mode)
+
       io.seek(offset)
       font = read(io)
       font.initialize_storage
+      font.loading_mode = mode
       font.read_table_data(io)
       font
     end
@@ -97,19 +138,106 @@ module Fontisan
     def initialize_storage
       @table_data = {}
       @parsed_tables = {}
+      @loading_mode = LoadingModes::FULL
+      @lazy_load_enabled = false
+      @io_source = nil
+      @page_cache = {}
     end
 
     # Read table data for all tables
     #
+    # In metadata mode, only reads metadata tables. In full mode, reads all tables.
+    # In lazy load mode, doesn't read data upfront.
+    #
     # @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)
+
+      if @lazy_load_enabled
+        # Don't read data, just keep IO reference
+        @io_source = io
+        return
+      end
+
+      if @loading_mode == LoadingModes::METADATA
+        # Only read metadata tables for performance
+        # Use page-aware batched reading to maximize filesystem prefetching
+        read_metadata_tables_batched(io)
+      else
+        # Read all tables
+        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
+    end
+
+    # Read metadata tables using page-aware batching
+    #
+    # Groups adjacent tables within page boundaries and reads them together
+    # to maximize filesystem prefetching and minimize random seeks.
+    #
+    # @param io [IO] Open file handle
+    # @return [void]
+    def read_metadata_tables_batched(io)
+      # Typical filesystem page size (4KB is common, but 8KB gives better prefetch window)
+      page_threshold = 8192
+
+      # Get metadata tables sorted by offset for sequential access
+      metadata_entries = tables.select { |entry| LoadingModes::METADATA_TABLES_SET.include?(entry.tag) }
+      metadata_entries.sort_by!(&:offset)
+
+      return if metadata_entries.empty?
+
+      # Group adjacent tables within page threshold for batched reading
+      i = 0
+      while i < metadata_entries.size
+        batch_start = metadata_entries[i]
+        batch_end = batch_start
+        batch_entries = [batch_start]
+
+        # Extend batch while next table is within page threshold
+        j = i + 1
+        while j < metadata_entries.size
+          next_entry = metadata_entries[j]
+          gap = next_entry.offset - (batch_end.offset + batch_end.table_length)
+
+          # If gap is small (within page threshold), include in batch
+          if gap <= page_threshold
+            batch_end = next_entry
+            batch_entries << next_entry
+            j += 1
+          else
+            break
+          end
+        end
+
+        # Read batch
+        if batch_entries.size == 1
+          # Single table, read normally
+          io.seek(batch_start.offset)
+          tag_key = batch_start.tag.dup.force_encoding("UTF-8")
+          @table_data[tag_key] = io.read(batch_start.table_length)
+        else
+          # Multiple tables, read contiguous segment
+          batch_offset = batch_start.offset
+          batch_length = (batch_end.offset + batch_end.table_length) - batch_start.offset
+
+          io.seek(batch_offset)
+          batch_data = io.read(batch_length)
+
+          # Extract individual tables from batch
+          batch_entries.each do |entry|
+            relative_offset = entry.offset - batch_offset
+            tag_key = entry.tag.dup.force_encoding("UTF-8")
+            @table_data[tag_key] = batch_data[relative_offset, entry.table_length]
+          end
+        end
+
+        i = j
       end
     end
 
@@ -159,6 +287,15 @@ module Fontisan
       tables.any? { |entry| entry.tag == tag }
     end
 
+    # Check if a table is available in the current loading mode
+    #
+    # @param tag [String] The table tag to check
+    # @return [Boolean] true if table is available in current mode
+    def table_available?(tag)
+      return false unless has_table?(tag)
+      LoadingModes.table_allowed?(@loading_mode, tag)
+    end
+
     # Find a table entry by tag
     #
     # @param tag [String] The table tag to find
@@ -184,11 +321,30 @@ module Fontisan
     # 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.
+    # and caches the result for subsequent calls. Enforces mode restrictions.
     #
     # @param tag [String] The table tag to retrieve
     # @return [Tables::*, nil] Parsed table object or nil if not found
+    # @raise [ArgumentError] if table is not available in current loading mode
     def table(tag)
+      # Check mode restrictions
+      unless table_available?(tag)
+        if has_table?(tag)
+          raise ArgumentError,
+                "Table '#{tag}' is not available in #{@loading_mode} mode. " \
+                "Available tables: #{LoadingModes.tables_for(@loading_mode).inspect}"
+        else
+          return nil
+        end
+      end
+
+      return @parsed_tables[tag] if @parsed_tables.key?(tag)
+
+      # Lazy load table data if enabled
+      if @lazy_load_enabled && !@table_data.key?(tag)
+        load_table_data(tag)
+      end
+
       @parsed_tables[tag] ||= parse_table(tag)
     end
 
@@ -200,8 +356,133 @@ module Fontisan
       head&.units_per_em
     end
 
+    # Convenience methods for accessing common name table fields
+    # These are particularly useful in minimal mode
+
+    # Get font family name
+    #
+    # @return [String, nil] Family name or nil if not found
+    def family_name
+      name_table = table(Constants::NAME_TAG)
+      name_table&.english_name(Tables::Name::FAMILY)
+    end
+
+    # Get font subfamily name (e.g., Regular, Bold, Italic)
+    #
+    # @return [String, nil] Subfamily name or nil if not found
+    def subfamily_name
+      name_table = table(Constants::NAME_TAG)
+      name_table&.english_name(Tables::Name::SUBFAMILY)
+    end
+
+    # Get full font name
+    #
+    # @return [String, nil] Full name or nil if not found
+    def full_name
+      name_table = table(Constants::NAME_TAG)
+      name_table&.english_name(Tables::Name::FULL_NAME)
+    end
+
+    # Get PostScript name
+    #
+    # @return [String, nil] PostScript name or nil if not found
+    def post_script_name
+      name_table = table(Constants::NAME_TAG)
+      name_table&.english_name(Tables::Name::POSTSCRIPT_NAME)
+    end
+
+    # Get preferred family name
+    #
+    # @return [String, nil] Preferred family name or nil if not found
+    def preferred_family_name
+      name_table = table(Constants::NAME_TAG)
+      name_table&.english_name(Tables::Name::PREFERRED_FAMILY)
+    end
+
+    # Get preferred subfamily name
+    #
+    # @return [String, nil] Preferred subfamily name or nil if not found
+    def preferred_subfamily_name
+      name_table = table(Constants::NAME_TAG)
+      name_table&.english_name(Tables::Name::PREFERRED_SUBFAMILY)
+    end
+
+    # Close the IO source (for lazy loading)
+    #
+    # @return [void]
+    def close
+      @io_source&.close
+      @io_source = nil
+    end
+
+    # Setup finalizer for cleanup
+    #
+    # @return [void]
+    def setup_finalizer
+      ObjectSpace.define_finalizer(self, self.class.finalize(@io_source))
+    end
+
+    # Finalizer proc for closing IO
+    #
+    # @param io [IO] The IO object to close
+    # @return [Proc] The finalizer proc
+    def self.finalize(io)
+      proc { io&.close }
+    end
+
     private
 
+    # Load a single table's data on demand
+    #
+    # Uses page-aligned reads and caches pages to ensure lazy loading
+    # performance is not slower than eager loading.
+    #
+    # @param tag [String] The table tag to load
+    # @return [void]
+    def load_table_data(tag)
+      return unless @io_source
+
+      entry = find_table_entry(tag)
+      return nil unless entry
+
+      # Use page-aligned reading with caching
+      table_start = entry.offset
+      table_end = entry.offset + entry.table_length
+
+      # Calculate page boundaries
+      page_start = (table_start / PAGE_SIZE) * PAGE_SIZE
+      page_end = ((table_end + PAGE_SIZE - 1) / PAGE_SIZE) * PAGE_SIZE
+
+      # Read all required pages (or use cached pages)
+      table_data_parts = []
+      current_page = page_start
+
+      while current_page < page_end
+        page_data = @page_cache[current_page]
+
+        unless page_data
+          # Read page from disk and cache it
+          @io_source.seek(current_page)
+          page_data = @io_source.read(PAGE_SIZE) || ""
+          @page_cache[current_page] = page_data
+        end
+
+        # Calculate which part of this page we need
+        chunk_start = [table_start - current_page, 0].max
+        chunk_end = [table_end - current_page, PAGE_SIZE].min
+
+        if chunk_end > chunk_start
+          table_data_parts << page_data[chunk_start...chunk_end]
+        end
+
+        current_page += PAGE_SIZE
+      end
+
+      # Combine parts and store
+      tag_key = tag.dup.force_encoding("UTF-8")
+      @table_data[tag_key] = table_data_parts.join
+    end
+
     # Parse a table from raw data (Fontisan extension)
     #
     # @param tag [String] The table tag to parse
@@ -223,6 +504,9 @@ module Fontisan
     def table_class_for(tag)
       {
         Constants::HEAD_TAG => Tables::Head,
+        Constants::HHEA_TAG => Tables::Hhea,
+        Constants::HMTX_TAG => Tables::Hmtx,
+        Constants::MAXP_TAG => Tables::Maxp,
         Constants::NAME_TAG => Tables::Name,
         Constants::OS2_TAG => Tables::Os2,
         Constants::POST_TAG => Tables::Post,
@@ -230,6 +514,8 @@ module Fontisan
         Constants::FVAR_TAG => Tables::Fvar,
         Constants::GSUB_TAG => Tables::Gsub,
         Constants::GPOS_TAG => Tables::Gpos,
+        Constants::GLYF_TAG => Tables::Glyf,
+        Constants::LOCA_TAG => Tables::Loca,
       }[tag]
     end
 
@@ -283,7 +569,7 @@ module Fontisan
         directory_offset_position = 12 + (index * 16) + 8
         current_pos = io.pos
         io.seek(directory_offset_position)
-        io.write([current_position].pack("N"))
+        io.write([current_position].pack("N")) # Offset is now known
         io.seek(current_pos)
       end
     end

data/lib/fontisan/utilities/brotli_wrapper.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "brotli"
+
+module Fontisan
+  module Utilities
+    # Wrapper for Brotli compression with consistent settings
+    #
+    # [`BrotliWrapper`](lib/fontisan/utilities/brotli_wrapper.rb) provides
+    # a consistent interface for Brotli compression with configurable quality
+    # and error handling. Used primarily for WOFF2 encoding.
+    #
+    # Brotli compression is significantly more effective than zlib (used in WOFF),
+    # typically achieving 20-30% better compression ratios on font data.
+    #
+    # @example Compress table data
+    #   compressed = BrotliWrapper.compress(table_data, quality: 11)
+    #
+    # @example Decompress data
+    #   decompressed = BrotliWrapper.decompress(compressed_data)
+    class BrotliWrapper
+      # Default compression quality (0-11, higher = better but slower)
+      # Quality 11 gives best compression for WOFF2
+      DEFAULT_QUALITY = 11
+
+      # Minimum quality level
+      MIN_QUALITY = 0
+
+      # Maximum quality level
+      MAX_QUALITY = 11
+
+      # Compress data using Brotli
+      #
+      # @param data [String] Data to compress
+      # @param quality [Integer] Compression quality (0-11)
+      # @param mode [Symbol] Compression mode (:generic, :text, :font)
+      # @return [String] Compressed data
+      # @raise [ArgumentError] If quality is out of range
+      # @raise [Error] If compression fails
+      #
+      # @example Compress with default quality
+      #   compressed = BrotliWrapper.compress(data)
+      #
+      # @example Compress with specific quality
+      #   compressed = BrotliWrapper.compress(data, quality: 9)
+      def self.compress(data, quality: DEFAULT_QUALITY, mode: :font)
+        validate_quality!(quality)
+        validate_data!(data)
+
+        begin
+          # Use Brotli gem with specified quality
+          # The brotli gem doesn't expose mode constants, only quality
+          Brotli.deflate(data, quality: quality)
+        rescue StandardError => e
+          raise Fontisan::Error,
+                "Brotli compression failed: #{e.message}"
+        end
+      end
+
+      # Decompress Brotli-compressed data
+      #
+      # @param data [String] Compressed data
+      # @return [String] Decompressed data
+      # @raise [Error] If decompression fails
+      #
+      # @example
+      #   decompressed = BrotliWrapper.decompress(compressed_data)
+      def self.decompress(data)
+        validate_data!(data)
+
+        begin
+          Brotli.inflate(data)
+        rescue StandardError => e
+          raise Fontisan::Error,
+                "Brotli decompression failed: #{e.message}"
+        end
+      end
+
+      # Calculate compression ratio
+      #
+      # @param original_size [Integer] Original data size
+      # @param compressed_size [Integer] Compressed data size
+      # @return [Float] Compression ratio (0.0-1.0)
+      #
+      # @example
+      #   ratio = BrotliWrapper.compression_ratio(1000, 300)
+      #   # => 0.3 (30% of original size)
+      def self.compression_ratio(original_size, compressed_size)
+        return 0.0 if original_size.zero?
+
+        compressed_size.to_f / original_size
+      end
+
+      # Calculate compression percentage
+      #
+      # @param original_size [Integer] Original data size
+      # @param compressed_size [Integer] Compressed data size
+      # @return [Float] Compression percentage reduction
+      #
+      # @example
+      #   pct = BrotliWrapper.compression_percentage(1000, 300)
+      #   # => 70.0 (70% reduction)
+      def self.compression_percentage(original_size, compressed_size)
+        return 0.0 if original_size.zero?
+
+        ((original_size - compressed_size).to_f / original_size * 100).round(1)
+      end
+
+      class << self
+        private
+
+        # Validate compression quality parameter
+        #
+        # @param quality [Integer] Quality level
+        # @raise [ArgumentError] If quality is invalid
+        def validate_quality!(quality)
+          unless quality.is_a?(Integer)
+            raise ArgumentError,
+                  "Quality must be an Integer, got #{quality.class}"
+          end
+
+          unless (MIN_QUALITY..MAX_QUALITY).cover?(quality)
+            raise ArgumentError,
+                  "Quality must be between #{MIN_QUALITY} and #{MAX_QUALITY}, " \
+                  "got #{quality}"
+          end
+        end
+
+        # Validate data parameter
+        #
+        # @param data [String] Data to validate
+        # @raise [ArgumentError] If data is invalid
+        def validate_data!(data)
+          if data.nil?
+            raise ArgumentError, "Data cannot be nil"
+          end
+
+          unless data.respond_to?(:bytesize)
+            raise ArgumentError,
+                  "Data must be a String-like object, got #{data.class}"
+          end
+        end
+
+        # Convert mode symbol to Brotli constant
+        #
+        # NOTE: The brotli gem doesn't expose mode constants
+        # This method is kept for API compatibility but unused
+        #
+        # @param mode [Symbol] Mode symbol
+        # @return [Integer] Mode value (unused)
+        def brotli_mode(_mode)
+          # The brotli gem only accepts quality parameter
+          # Mode is not configurable in current version
+          0
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/utilities/checksum_calculator.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "stringio"
 require_relative "../constants"
 
 module Fontisan
@@ -55,6 +56,23 @@ module Fontisan
         (Constants::CHECKSUM_ADJUSTMENT_MAGIC - file_checksum) & 0xFFFFFFFF
       end
 
+      # Calculate checksum for raw table data.
+      #
+      # This method calculates the checksum for a binary string of table data.
+      # Used when creating WOFF files or validating table integrity.
+      #
+      # @param data [String] binary table data
+      # @return [Integer] the calculated uint32 checksum
+      #
+      # @example
+      #   checksum = ChecksumCalculator.calculate_table_checksum(table_data)
+      #   # => 1234567890
+      def self.calculate_table_checksum(data)
+        io = StringIO.new(data)
+        io.set_encoding(Encoding::BINARY)
+        calculate_checksum_from_io(io)
+      end
+
       # Calculate checksum from an IO object.
       #
       # Reads the IO stream in 4-byte chunks and calculates the uint32 checksum.