fontisan 0.1.0 → 0.2.0

data/lib/fontisan/open_type_font.rb

@@ -2,6 +2,7 @@
 
 require "bindata"
 require_relative "constants"
+require_relative "loading_modes"
 require_relative "utilities/checksum_calculator"
 
 module Fontisan
@@ -16,6 +17,11 @@ module Fontisan
   #   name_table = otf.table("name")
   #   puts name_table.english_name(Tables::Name::FAMILY)
   #
+  # @example Loading with metadata mode
+  #   otf = OpenTypeFont.from_file("font.otf", mode: :metadata)
+  #   puts otf.loading_mode  # => :metadata
+  #   otf.table_available?("GSUB")  # => false
+  #
   # @example Writing a font
   #   otf.to_file("output.otf")
   class OpenTypeFont < BinData::Record
@@ -32,24 +38,55 @@ module Fontisan
     # Parsed table instances cache
     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 OpenType Font from a file
     #
     # @param path [String] Path to the OTF 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 [OpenTypeFont] 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
@@ -60,11 +97,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 [OpenTypeFont] A new instance
-    def self.from_collection(io, offset)
+    def self.from_collection(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
@@ -75,19 +116,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
 
@@ -138,6 +266,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
@@ -163,11 +300,30 @@ module Fontisan
     # Get parsed table instance
     #
     # 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
 
@@ -179,8 +335,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
     #
     # @param tag [String] The table tag to parse
@@ -202,6 +483,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,
@@ -209,6 +493,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
 

data/lib/fontisan/optimizers/charstring_rewriter.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Optimizers
+    # Rewrites CharStrings by replacing repeated patterns with subroutine calls.
+    # Uses position-aware replacement to handle multiple patterns per glyph
+    # without offset corruption.
+    #
+    # @example Basic usage
+    #   builder = SubroutineBuilder.new(patterns, type: :local)
+    #   builder.build
+    #   subroutine_map = patterns.each_with_index.to_h { |p, i| [p.bytes, i] }
+    #   rewriter = CharstringRewriter.new(subroutine_map, builder)
+    #   rewritten = rewriter.rewrite(charstring, patterns_for_glyph)
+    #   valid = rewriter.validate(rewritten)
+    #
+    # @see docs/SUBROUTINE_ARCHITECTURE.md
+    class CharstringRewriter
+      # Initialize rewriter with subroutine map and builder
+      # @param subroutine_map [Hash<String, Integer>] pattern bytes => subroutine_id
+      # @param builder [SubroutineBuilder] builder for creating calls
+      def initialize(subroutine_map, builder)
+        @subroutine_map = subroutine_map
+        @builder = builder
+      end
+
+      # Rewrite a CharString by replacing patterns with subroutine calls
+      # Sorts patterns by position (descending) to avoid offset issues when
+      # replacing multiple patterns in the same CharString.
+      #
+      # @param charstring [String] original CharString bytes
+      # @param patterns [Array<Pattern>] patterns to replace in this CharString
+      # @return [String] rewritten CharString with subroutine calls
+      def rewrite(charstring, patterns)
+        return charstring if patterns.empty?
+
+        # Build list of all replacements: [position, pattern]
+        replacements = build_replacement_list(charstring, patterns)
+
+        # Remove overlapping replacements
+        replacements = remove_overlaps(replacements)
+
+        # Sort by position (descending) to avoid offset corruption
+        replacements.sort_by! { |pos, _pattern| -pos }
+
+        # Apply each replacement
+        rewritten = charstring.dup
+        replacements.each do |position, pattern|
+          subroutine_id = @subroutine_map[pattern.bytes]
+          next if subroutine_id.nil?
+
+          call = @builder.create_call(subroutine_id)
+
+          # Replace pattern with call at position
+          rewritten[position, pattern.length] = call
+        end
+
+        rewritten
+      end
+
+      # Validate rewritten CharString for structural correctness
+      # For now, performs basic validation. Future: full CFF parsing.
+      #
+      # @param charstring [String] CharString to validate
+      # @return [Boolean] true if valid, false otherwise
+      def validate(charstring)
+        return false if charstring.nil? || charstring.empty?
+
+        # Basic validation: check for return operator at end
+        # and reasonable length
+        return false if charstring.empty?
+
+        # More comprehensive validation can be added later
+        true
+      end
+
+      private
+
+      # Remove overlapping replacements, keeping higher-value patterns
+      # When two patterns occupy overlapping byte positions, we keep the one
+      # with higher savings to maximize total optimization benefit.
+      #
+      # @param replacements [Array<Array>] array of [position, pattern] pairs
+      # @return [Array<Array>] non-overlapping replacements
+      def remove_overlaps(replacements)
+        return replacements if replacements.empty?
+
+        # Sort by position (ascending) then by savings (descending)
+        sorted = replacements.sort_by { |pos, pattern| [pos, -pattern.savings] }
+
+        non_overlapping = []
+        last_end = 0
+
+        sorted.each do |position, pattern|
+          pattern_end = position + pattern.length
+
+          # Check if this replacement starts after the last one ended
+          if position >= last_end
+            # No overlap - add this replacement
+            non_overlapping << [position, pattern]
+            last_end = pattern_end
+          elsif non_overlapping.any?
+            # Overlap detected - compare with previous
+            prev_position, prev_pattern = non_overlapping.last
+            prev_position + prev_pattern.length
+
+            # If current pattern has higher savings, replace the previous one
+            if pattern.savings > prev_pattern.savings
+              # Current pattern is more valuable - replace previous
+              non_overlapping[-1] = [position, pattern]
+              last_end = pattern_end
+            end
+            # else: keep previous, skip current
+          end
+        end
+
+        non_overlapping
+      end
+
+      # Build list of all pattern replacements with their positions
+      # @param charstring [String] CharString being rewritten
+      # @param patterns [Array<Pattern>] patterns to find
+      # @return [Array<Array>] array of [position, pattern] pairs
+      def build_replacement_list(charstring, patterns)
+        replacements = []
+
+        patterns.each do |pattern|
+          # Find all positions where this pattern occurs
+          positions = find_pattern_positions(charstring, pattern)
+
+          positions.each do |position|
+            replacements << [position, pattern]
+          end
+        end
+
+        replacements
+      end
+
+      # Find all positions where a pattern occurs in the CharString
+      # @param charstring [String] CharString to search
+      # @param pattern [Pattern] pattern to find
+      # @return [Array<Integer>] array of start positions
+      def find_pattern_positions(charstring, pattern)
+        positions = []
+        offset = 0
+
+        while offset <= charstring.length - pattern.length
+          if charstring[offset, pattern.length] == pattern.bytes
+            positions << offset
+            # Move past this occurrence
+            offset += pattern.length
+          else
+            offset += 1
+          end
+        end
+
+        positions
+      end
+    end
+  end
+end