fontisan 0.1.0 → 0.2.0

data/lib/fontisan/export/ttx_parser.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Fontisan
+  module Export
+    # TtxParser parses TTX XML format to font data
+    #
+    # Parses fonttools-compatible TTX XML files and reconstructs
+    # font data that can be written back to binary formats.
+    #
+    # @example Parsing TTX file
+    #   parser = TtxParser.new
+    #   font_data = parser.parse(File.read("font.ttx"))
+    #   # Use font_data to rebuild binary font
+    class TtxParser
+      # Parse TTX XML content
+      #
+      # @param ttx_xml [String] TTX XML content
+      # @return [Hash] Parsed font data structure
+      def parse(ttx_xml)
+        doc = Nokogiri::XML(ttx_xml)
+        ttfont = doc.at_xpath("/ttFont")
+        raise "No ttFont root element found" unless ttfont
+
+        {
+          sfnt_version: parse_sfnt_version(ttfont["sfntVersion"]),
+          glyph_order: parse_glyph_order(ttfont),
+          tables: parse_tables(ttfont),
+        }
+      end
+
+      private
+
+      # Parse SFNT version
+      #
+      # @param version_str [String] Version string
+      # @return [Integer] Version integer
+      def parse_sfnt_version(version_str)
+        # Handle format like "\x00\x01\x00\x00" or "0x00010000"
+        if version_str.start_with?("\\x")
+          # Parse escaped hex bytes
+          bytes = version_str.scan(/\\x([0-9a-f]{2})/i).flatten
+          bytes.map { |b| b.to_i(16) }.pack("C*").unpack1("N")
+        elsif version_str.start_with?("0x")
+          version_str.to_i(16)
+        else
+          version_str.to_i
+        end
+      end
+
+      # Parse GlyphOrder section
+      #
+      # @param ttfont [Nokogiri::XML::Element] Root element
+      # @return [Array<Hash>] Array of glyph entries
+      def parse_glyph_order(ttfont)
+        glyph_order = ttfont.at_xpath("GlyphOrder")
+        return [] unless glyph_order
+
+        glyph_order.xpath("GlyphID").map do |glyph_id|
+          {
+            id: glyph_id["id"].to_i,
+            name: glyph_id["name"],
+          }
+        end
+      end
+
+      # Parse all tables
+      #
+      # @param ttfont [Nokogiri::XML::Element] Root element
+      # @return [Hash] Hash of table data by tag
+      def parse_tables(ttfont)
+        tables = {}
+
+        # Parse specific tables
+        parse_head_table(ttfont, tables)
+        parse_hhea_table(ttfont, tables)
+        parse_maxp_table(ttfont, tables)
+        parse_name_table(ttfont, tables)
+        parse_os2_table(ttfont, tables)
+        parse_post_table(ttfont, tables)
+
+        # Parse any remaining binary tables
+        parse_binary_tables(ttfont, tables)
+
+        tables
+      end
+
+      # Parse head table
+      #
+      # @param ttfont [Nokogiri::XML::Element] Root element
+      # @param tables [Hash] Tables hash
+      # @return [void]
+      def parse_head_table(ttfont, tables)
+        head = ttfont.at_xpath("head")
+        return unless head
+
+        tables["head"] = {
+          table_version: parse_fixed(head.at_xpath("tableVersion")&.[]("value")),
+          font_revision: parse_fixed(head.at_xpath("fontRevision")&.[]("value")),
+          checksum_adjustment: parse_hex(head.at_xpath("checkSumAdjustment")&.[]("value")),
+          magic_number: parse_hex(head.at_xpath("magicNumber")&.[]("value")),
+          flags: head.at_xpath("flags")&.[]("value").to_i,
+          units_per_em: head.at_xpath("unitsPerEm")&.[]("value").to_i,
+          created: parse_timestamp(head.at_xpath("created")&.[]("value")),
+          modified: parse_timestamp(head.at_xpath("modified")&.[]("value")),
+          x_min: head.at_xpath("xMin")&.[]("value").to_i,
+          y_min: head.at_xpath("yMin")&.[]("value").to_i,
+          x_max: head.at_xpath("xMax")&.[]("value").to_i,
+          y_max: head.at_xpath("yMax")&.[]("value").to_i,
+          mac_style: parse_binary_flags(head.at_xpath("macStyle")&.[]("value")),
+          lowest_rec_ppem: head.at_xpath("lowestRecPPEM")&.[]("value").to_i,
+          font_direction_hint: head.at_xpath("fontDirectionHint")&.[]("value").to_i,
+          index_to_loc_format: head.at_xpath("indexToLocFormat")&.[]("value").to_i,
+          glyph_data_format: head.at_xpath("glyphDataFormat")&.[]("value").to_i,
+        }
+      end
+
+      # Parse hhea table
+      #
+      # @param ttfont [Nokogiri::XML::Element] Root element
+      # @param tables [Hash] Tables hash
+      # @return [void]
+      def parse_hhea_table(ttfont, tables)
+        hhea = ttfont.at_xpath("hhea")
+        return unless hhea
+
+        tables["hhea"] = {
+          table_version: parse_hex(hhea.at_xpath("tableVersion")&.[]("value")),
+          ascent: hhea.at_xpath("ascent")&.[]("value").to_i,
+          descent: hhea.at_xpath("descent")&.[]("value").to_i,
+          line_gap: hhea.at_xpath("lineGap")&.[]("value").to_i,
+          advance_width_max: hhea.at_xpath("advanceWidthMax")&.[]("value").to_i,
+          min_left_side_bearing: hhea.at_xpath("minLeftSideBearing")&.[]("value").to_i,
+          min_right_side_bearing: hhea.at_xpath("minRightSideBearing")&.[]("value").to_i,
+          x_max_extent: hhea.at_xpath("xMaxExtent")&.[]("value").to_i,
+          caret_slope_rise: hhea.at_xpath("caretSlopeRise")&.[]("value").to_i,
+          caret_slope_run: hhea.at_xpath("caretSlopeRun")&.[]("value").to_i,
+          caret_offset: hhea.at_xpath("caretOffset")&.[]("value").to_i,
+          metric_data_format: hhea.at_xpath("metricDataFormat")&.[]("value").to_i,
+          number_of_h_metrics: hhea.at_xpath("numberOfHMetrics")&.[]("value").to_i,
+        }
+      end
+
+      # Parse maxp table
+      #
+      # @param ttfont [Nokogiri::XML::Element] Root element
+      # @param tables [Hash] Tables hash
+      # @return [void]
+      def parse_maxp_table(ttfont, tables)
+        maxp = ttfont.at_xpath("maxp")
+        return unless maxp
+
+        tables["maxp"] = {
+          table_version: parse_hex(maxp.at_xpath("tableVersion")&.[]("value")),
+          num_glyphs: maxp.at_xpath("numGlyphs")&.[]("value").to_i,
+        }
+
+        # Version 1.0 fields
+        if tables["maxp"][:table_version] >= 0x00010000
+          tables["maxp"].merge!({
+                                  max_points: maxp.at_xpath("maxPoints")&.[]("value")&.to_i,
+                                  max_contours: maxp.at_xpath("maxContours")&.[]("value")&.to_i,
+                                  max_composite_points: maxp.at_xpath("maxCompositePoints")&.[]("value")&.to_i,
+                                  max_composite_contours: maxp.at_xpath("maxCompositeContours")&.[]("value")&.to_i,
+                                })
+        end
+      end
+
+      # Parse name table
+      #
+      # @param ttfont [Nokogiri::XML::Element] Root element
+      # @param tables [Hash] Tables hash
+      # @return [void]
+      def parse_name_table(ttfont, tables)
+        name_elem = ttfont.at_xpath("name")
+        return unless name_elem
+
+        name_records = name_elem.xpath("namerecord").map do |record|
+          {
+            name_id: record["nameID"].to_i,
+            platform_id: record["platformID"].to_i,
+            encoding_id: record["platEncID"].to_i,
+            language_id: parse_hex(record["langID"]),
+            string: record.text,
+          }
+        end
+
+        tables["name"] = { name_records: name_records }
+      end
+
+      # Parse OS/2 table (stub)
+      #
+      # @param ttfont [Nokogiri::XML::Element] Root element
+      # @param tables [Hash] Tables hash
+      # @return [void]
+      def parse_os2_table(ttfont, tables)
+        os2 = ttfont.at_xpath("OS/2")
+        return unless os2
+
+        # Basic OS/2 parsing - can be expanded
+        tables["OS/2"] = { parsed: false }
+      end
+
+      # Parse post table (stub)
+      #
+      # @param ttfont [Nokogiri::XML::Element] Root element
+      # @param tables [Hash] Tables hash
+      # @return [void]
+      def parse_post_table(ttfont, tables)
+        post = ttfont.at_xpath("post")
+        return unless post
+
+        tables["post"] = {
+          format_type: parse_fixed(post.at_xpath("formatType")&.[]("value")),
+          italic_angle: parse_fixed(post.at_xpath("italicAngle")&.[]("value")),
+          underline_position: post.at_xpath("underlinePosition")&.[]("value").to_i,
+          underline_thickness: post.at_xpath("underlineThickness")&.[]("value").to_i,
+          is_fixed_pitch: post.at_xpath("isFixedPitch")&.[]("value").to_i,
+        }
+      end
+
+      # Parse binary tables (fallback)
+      #
+      # @param ttfont [Nokogiri::XML::Element] Root element
+      # @param tables [Hash] Tables hash
+      # @return [void]
+      def parse_binary_tables(ttfont, tables)
+        # Find all table elements not already parsed
+        ttfont.children.each do |elem|
+          next unless elem.element?
+          next if elem.name == "GlyphOrder"
+          next if tables.key?(elem.name)
+
+          hexdata = elem.at_xpath("hexdata")
+          if hexdata
+            tables[elem.name] = {
+              binary: parse_hex_data(hexdata.text),
+            }
+          end
+        end
+      end
+
+      # Parse fixed-point number
+      #
+      # @param value_str [String] Fixed-point string
+      # @return [Integer] Fixed-point integer (16.16)
+      def parse_fixed(value_str)
+        return 0 unless value_str
+
+        (value_str.to_f * 65536).to_i
+      end
+
+      # Parse hex value
+      #
+      # @param value_str [String] Hex string
+      # @return [Integer] Integer value
+      def parse_hex(value_str)
+        return 0 unless value_str
+
+        value_str.to_i(16)
+      end
+
+      # Parse binary flags
+      #
+      # @param flags_str [String] Binary string with spaces
+      # @return [Integer] Integer value
+      def parse_binary_flags(flags_str)
+        return 0 unless flags_str
+
+        flags_str.gsub(/\s+/, "").to_i(2)
+      end
+
+      # Parse timestamp
+      #
+      # @param timestamp_str [String] Timestamp string
+      # @return [Integer] Mac timestamp
+      def parse_timestamp(timestamp_str)
+        return 0 unless timestamp_str
+
+        begin
+          time = Time.strptime(timestamp_str, "%a %b %e %H:%M:%S %Y")
+          mac_epoch = Time.utc(1904, 1, 1)
+          (time - mac_epoch).to_i
+        rescue StandardError
+          0
+        end
+      end
+
+      # Parse hex data
+      #
+      # @param hex_str [String] Hex string with newlines
+      # @return [String] Binary data
+      def parse_hex_data(hex_str)
+        hex_clean = hex_str.gsub(/\s+/, "")
+        [hex_clean].pack("H*")
+      end
+    end
+  end
+end

data/lib/fontisan/font_loader.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 require_relative "constants"
+require_relative "loading_modes"
 require_relative "true_type_font"
 require_relative "open_type_font"
 require_relative "true_type_collection"
 require_relative "open_type_collection"
+require_relative "woff_font"
+require_relative "woff2_font"
 require_relative "error"
 
 module Fontisan
@@ -19,35 +22,52 @@ module Fontisan
   #   font = FontLoader.load("font.otf")  # => OpenTypeFont
   #   font = FontLoader.load("fonts.ttc") # => TrueTypeFont (first in collection)
   #   font = FontLoader.load("fonts.ttc", font_index: 2) # => TrueTypeFont (third in collection)
+  #
+  # @example Loading modes
+  #   font = FontLoader.load("font.ttf", mode: :metadata)  # Load only metadata tables
+  #   font = FontLoader.load("font.ttf", mode: :full)      # Load all tables
+  #
+  # @example Lazy loading control
+  #   font = FontLoader.load("font.ttf", lazy: true)   # Tables loaded on-demand
+  #   font = FontLoader.load("font.ttf", lazy: false)  # All tables loaded upfront
   class FontLoader
     # Load a font from file with automatic format detection
     #
     # @param path [String] Path to the font file
     # @param font_index [Integer] Index of font in collection (0-based, default: 0)
-    # @return [TrueTypeFont, OpenTypeFont] The loaded font object
+    # @param mode [Symbol] Loading mode (:metadata or :full, default: from ENV or :full)
+    # @param lazy [Boolean] If true, load tables on demand (default: false for eager loading)
+    # @return [TrueTypeFont, OpenTypeFont, WoffFont, Woff2Font] The loaded font object
     # @raise [Errno::ENOENT] if file does not exist
-    # @raise [UnsupportedFormatError] for WOFF/WOFF2 or other unsupported formats
+    # @raise [UnsupportedFormatError] for unsupported formats
     # @raise [InvalidFontError] for corrupted or unknown formats
-    def self.load(path, font_index: 0)
+    def self.load(path, font_index: 0, mode: nil, lazy: nil)
       raise Errno::ENOENT, "File not found: #{path}" unless File.exist?(path)
 
+      # Resolve mode and lazy parameters with environment variables
+      resolved_mode = mode || env_mode || LoadingModes::FULL
+      resolved_lazy = lazy.nil? ? (env_lazy.nil? ? false : env_lazy) : lazy
+
+      # Validate mode
+      LoadingModes.validate_mode!(resolved_mode)
+
       File.open(path, "rb") do |io|
         signature = io.read(4)
         io.rewind
 
         case signature
         when Constants::TTC_TAG
-          load_from_collection(io, path, font_index)
+          load_from_collection(io, path, font_index, mode: resolved_mode, lazy: resolved_lazy)
         when pack_uint32(Constants::SFNT_VERSION_TRUETYPE)
-          TrueTypeFont.from_file(path)
+          TrueTypeFont.from_file(path, mode: resolved_mode, lazy: resolved_lazy)
         when "OTTO"
-          OpenTypeFont.from_file(path)
+          OpenTypeFont.from_file(path, mode: resolved_mode, lazy: resolved_lazy)
         when "wOFF"
           raise UnsupportedFormatError,
-                "Unsupported font format: WOFF. Fontisan currently supports TTF, OTF, TTC, and OTC files."
+                "Unsupported font format: WOFF. Please convert to TTF/OTF first."
         when "wOF2"
           raise UnsupportedFormatError,
-                "Unsupported font format: WOFF2. Fontisan currently supports TTF, OTF, TTC, and OTC files."
+                "Unsupported font format: WOFF2. Please convert to TTF/OTF first."
         else
           raise InvalidFontError,
                 "Unknown font format. Expected TTF, OTF, TTC, or OTC file."
@@ -55,14 +75,103 @@ module Fontisan
       end
     end
 
+    # Check if a file is a collection (TTC or OTC)
+    #
+    # @param path [String] Path to the font file
+    # @return [Boolean] true if file is a TTC/OTC collection
+    # @raise [Errno::ENOENT] if file does not exist
+    #
+    # @example Check if file is collection
+    #   FontLoader.collection?("fonts.ttc") # => true
+    #   FontLoader.collection?("font.ttf")  # => false
+    def self.collection?(path)
+      raise Errno::ENOENT, "File not found: #{path}" unless File.exist?(path)
+
+      File.open(path, "rb") do |io|
+        signature = io.read(4)
+        signature == Constants::TTC_TAG
+      end
+    end
+
+    # Load a collection object without extracting fonts
+    #
+    # Returns the collection object (TrueTypeCollection or OpenTypeCollection)
+    # without extracting individual fonts. Useful for inspecting collection
+    # metadata and structure.
+    #
+    # @param path [String] Path to the collection file
+    # @return [TrueTypeCollection, OpenTypeCollection] The collection object
+    # @raise [Errno::ENOENT] if file does not exist
+    # @raise [InvalidFontError] if file is not a collection or type cannot be determined
+    #
+    # @example Load collection for inspection
+    #   collection = FontLoader.load_collection("fonts.ttc")
+    #   puts "Collection has #{collection.num_fonts} fonts"
+    def self.load_collection(path)
+      raise Errno::ENOENT, "File not found: #{path}" unless File.exist?(path)
+
+      File.open(path, "rb") do |io|
+        signature = io.read(4)
+
+        unless signature == Constants::TTC_TAG
+          raise InvalidFontError,
+                "File is not a collection (TTC/OTC). Use FontLoader.load instead."
+        end
+
+        # Read first font offset to detect collection type
+        io.seek(12) # Skip tag (4) + versions (4) + num_fonts (4)
+        first_offset = io.read(4).unpack1("N")
+
+        # Peek at first font's sfnt_version
+        io.seek(first_offset)
+        sfnt_version = io.read(4).unpack1("N")
+        io.rewind
+
+        case sfnt_version
+        when Constants::SFNT_VERSION_TRUETYPE
+          TrueTypeCollection.from_file(path)
+        when Constants::SFNT_VERSION_OTTO
+          OpenTypeCollection.from_file(path)
+        else
+          raise InvalidFontError,
+                "Unknown font type in collection (sfnt version: 0x#{sfnt_version.to_s(16)})"
+        end
+      end
+    end
+
+    # Get mode from environment variable
+    #
+    # @return [Symbol, nil] Mode from FONTISAN_MODE or nil
+    # @api private
+    def self.env_mode
+      env_value = ENV["FONTISAN_MODE"]
+      return nil unless env_value
+
+      mode = env_value.to_sym
+      LoadingModes.valid_mode?(mode) ? mode : nil
+    end
+
+    # Get lazy setting from environment variable
+    #
+    # @return [Boolean, nil] Lazy setting from FONTISAN_LAZY or nil if not set
+    # @api private
+    def self.env_lazy
+      env_value = ENV["FONTISAN_LAZY"]
+      return nil unless env_value
+
+      env_value.downcase == "true"
+    end
+
     # Load from a collection file (TTC or OTC)
     #
     # @param io [IO] Open file handle
     # @param path [String] Path to the collection file
     # @param font_index [Integer] Index of font to extract
+    # @param mode [Symbol] Loading mode (:metadata or :full)
+    # @param lazy [Boolean] If true, load tables on demand
     # @return [TrueTypeFont, OpenTypeFont] The loaded font object
     # @raise [InvalidFontError] if collection type cannot be determined
-    def self.load_from_collection(io, path, font_index)
+    def self.load_from_collection(io, path, font_index, mode: LoadingModes::FULL, lazy: true)
       # Read collection header to get font offsets
       io.seek(12) # Skip tag (4) + major_version (2) + minor_version (2) + num_fonts marker (4)
       num_fonts = io.read(4).unpack1("N")
@@ -84,11 +193,11 @@ module Fontisan
       when Constants::SFNT_VERSION_TRUETYPE
         # TrueType Collection
         ttc = TrueTypeCollection.from_file(path)
-        File.open(path, "rb") { |f| ttc.font(font_index, f) }
+        File.open(path, "rb") { |f| ttc.font(font_index, f, mode: mode) }
       when Constants::SFNT_VERSION_OTTO
         # OpenType Collection
         otc = OpenTypeCollection.from_file(path)
-        File.open(path, "rb") { |f| otc.font(font_index, f) }
+        File.open(path, "rb") { |f| otc.font(font_index, f, mode: mode) }
       else
         raise InvalidFontError,
               "Unknown font type in collection (sfnt version: 0x#{sfnt_version.to_s(16)})"
@@ -104,6 +213,6 @@ module Fontisan
       [value].pack("N")
     end
 
-    private_class_method :load_from_collection, :pack_uint32
+    private_class_method :load_from_collection, :pack_uint32, :env_mode, :env_lazy
   end
 end