fontisan 0.1.0 → 0.2.0

data/lib/fontisan/export/exporter.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require_relative "../models/font_export"
+require_relative "table_serializer"
+require_relative "ttx_generator"
+require_relative "transformers/font_to_ttx"
+require_relative "../utilities/checksum_calculator"
+
+module Fontisan
+  module Export
+    # Exporter orchestrates font export to YAML/JSON/TTX
+    #
+    # Main entry point for exporting fonts to debugging formats.
+    # Handles table extraction, serialization, and metadata generation.
+    #
+    # @example Exporting a font to YAML
+    #   exporter = Exporter.new(font, "font.ttf")
+    #   export = exporter.export(format: :yaml)
+    #   File.write("font.yaml", export.to_yaml)
+    #
+    # @example Exporting to TTX format
+    #   exporter = Exporter.new(font, "font.ttf")
+    #   ttx_xml = exporter.to_ttx
+    #   File.write("font.ttx", ttx_xml)
+    #
+    # @example Selective table export
+    #   export = exporter.export(tables: ["head", "name", "cmap"])
+    class Exporter
+      # Initialize exporter
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] The font to export
+      # @param source_path [String] Path to source font file
+      # @param options [Hash] Export options
+      # @option options [Symbol] :binary_format Format for binary data (:hex or :base64)
+      def initialize(font, source_path, options = {})
+        @font = font
+        @source_path = source_path
+        @binary_format = options.fetch(:binary_format, :hex)
+        @serializer = TableSerializer.new(binary_format: @binary_format)
+      end
+
+      # Export font to FontExport model
+      #
+      # @param options [Hash] Export options
+      # @option options [Array<String>] :tables Specific tables to export (default: all)
+      # @option options [Symbol] :format Output format (:yaml, :json, or :ttx)
+      # @return [Models::FontExport, String] The export model or TTX XML string
+      def export(options = {})
+        format = options[:format] || :yaml
+
+        if format == :ttx
+          to_ttx(options)
+        else
+          export_to_model(options)
+        end
+      end
+
+      # Export font and return as YAML string
+      #
+      # @param options [Hash] Export options
+      # @return [String] YAML representation
+      def to_yaml(options = {})
+        export_model = export_to_model(options)
+        export_model.to_yaml
+      end
+
+      # Export font and return as JSON string
+      #
+      # @param options [Hash] Export options
+      # @return [String] JSON representation
+      def to_json(options = {})
+        export_model = export_to_model(options)
+        export_model.to_json
+      end
+
+      # Export font and return as TTX XML string
+      #
+      # Uses model-based architecture with FontToTtx transformer
+      # and lutaml-model serialization.
+      #
+      # @param options [Hash] Export options
+      # @option options [Array<String>] :tables Specific tables to export
+      # @option options [Boolean] :pretty Pretty-print XML (default: true)
+      # @option options [Integer] :indent Indentation spaces (default: 2)
+      # @return [String] TTX XML representation
+      def to_ttx(options = {})
+        # Use new model-based architecture
+        transformer = Transformers::FontToTtx.new(@font)
+        ttx_model = transformer.transform(options)
+
+        # Let lutaml-model handle XML serialization
+        ttx_model.to_xml(
+          pretty: options.fetch(:pretty, true),
+          indent: options.fetch(:indent, 2),
+        )
+      end
+
+      private
+
+      # Export to FontExport model
+      #
+      # @param options [Hash] Export options
+      # @return [Models::FontExport] The export model
+      def export_to_model(options = {})
+        table_list = options[:tables] || :all
+
+        export_model = Models::FontExport.new
+        export_model.metadata = build_metadata
+        export_model.header = build_header
+
+        tables_to_export = select_tables(table_list)
+        tables_to_export.each do |tag|
+          export_table(export_model, tag)
+        end
+
+        export_model
+      end
+
+      # Build export metadata
+      #
+      # @return [Models::FontExport::Metadata]
+      def build_metadata
+        Models::FontExport::Metadata.new.tap do |meta|
+          meta.source_file = @source_path
+          meta.export_date = Time.now.utc.iso8601
+          meta.exporter_version = Fontisan::VERSION
+          meta.font_format = detect_font_format
+        end
+      end
+
+      # Build font header information
+      #
+      # @return [Models::FontExport::Header]
+      def build_header
+        Models::FontExport::Header.new.tap do |header|
+          header.sfnt_version = format_sfnt_version(@font.header.sfnt_version.to_i)
+          header.num_tables = @font.tables.size
+          header.search_range = @font.header.search_range.to_i
+          header.entry_selector = @font.header.entry_selector.to_i
+          header.range_shift = @font.header.range_shift.to_i
+        end
+      end
+
+      # Select tables to export
+      #
+      # @param table_list [Symbol, Array<String>] :all or list of table tags
+      # @return [Array<String>] Table tags to export
+      def select_tables(table_list)
+        if table_list == :all
+          @font.table_names
+        else
+          available = @font.table_names
+          requested = Array(table_list).map(&:to_s)
+          requested.select { |tag| available.include?(tag) }
+        end
+      end
+
+      # Export a single table
+      #
+      # @param export_model [Models::FontExport] The export model
+      # @param tag [String] The table tag
+      # @return [void]
+      def export_table(export_model, tag)
+        table = @font.table(tag)
+        return unless table
+
+        checksum = calculate_table_checksum(tag)
+        serialized = @serializer.serialize(table, tag)
+
+        export_model.add_table(
+          tag: tag,
+          checksum: format_checksum(checksum),
+          parsed: serialized[:parsed],
+          data: serialized[:data],
+          fields: serialized[:fields],
+        )
+      rescue StandardError => e
+        # If serialization fails, store as binary
+        export_binary_fallback(export_model, tag, e)
+      end
+
+      # Export table as binary fallback on error
+      #
+      # @param export_model [Models::FontExport] The export model
+      # @param tag [String] The table tag
+      # @param error [StandardError] The error that occurred
+      # @return [void]
+      def export_binary_fallback(export_model, tag, error)
+        table = @font.table(tag)
+        binary_data = table.respond_to?(:to_binary_s) ? table.to_binary_s : ""
+        checksum = calculate_table_checksum(tag)
+
+        export_model.add_table(
+          tag: tag,
+          checksum: format_checksum(checksum),
+          parsed: false,
+          data: @serializer.send(:encode_binary, binary_data),
+          fields: { error: error.message }.to_json,
+        )
+      end
+
+      # Calculate table checksum
+      #
+      # @param tag [String] Table tag
+      # @return [Integer] Checksum value
+      def calculate_table_checksum(tag)
+        table_entry = @font.tables.find { |entry| entry.tag == tag }
+        return 0 unless table_entry
+
+        if table_entry.respond_to?(:checksum)
+          table_entry.checksum.to_i
+        else
+          # Calculate from binary data
+          table = @font.table(tag)
+          data = table.respond_to?(:to_binary_s) ? table.to_binary_s : ""
+          Utilities::ChecksumCalculator.calculate(data)
+        end
+      end
+
+      # Format checksum as hex string
+      #
+      # @param checksum [Integer] Checksum value
+      # @return [String] Hex string (e.g., "0x12345678")
+      def format_checksum(checksum)
+        "0x#{checksum.to_s(16).upcase.rjust(8, '0')}"
+      end
+
+      # Format SFNT version
+      #
+      # @param version [Integer] SFNT version
+      # @return [String] Formatted version
+      def format_sfnt_version(version)
+        case version
+        when 0x00010000
+          "0x00010000 (TrueType)"
+        when 0x4F54544F # 'OTTO'
+          "0x4F54544F (OpenType/CFF)"
+        else
+          "0x#{version.to_s(16).upcase}"
+        end
+      end
+
+      # Detect font format
+      #
+      # @return [String] Font format name
+      def detect_font_format
+        case @font.class.name
+        when /TrueType/
+          "TrueType"
+        when /OpenType/
+          "OpenType"
+        when /Woff2/
+          "WOFF2"
+        when /Woff/
+          "WOFF"
+        else
+          "Unknown"
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/export/table_serializer.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+
+module Fontisan
+  module Export
+    # TableSerializer handles serialization of individual font tables
+    #
+    # Uses strategy pattern to serialize different table types:
+    # - Fully parsed tables: Use Lutaml::Model serialization
+    # - Binary tables: Encode as hex or base64
+    # - Special tables: Custom serialization logic
+    #
+    # @example Serializing a parsed table
+    #   serializer = TableSerializer.new(binary_format: :hex)
+    #   data = serializer.serialize(head_table, "head")
+    #
+    # @example Serializing binary table
+    #   data = serializer.serialize_binary(raw_data, "DSIG")
+    class TableSerializer
+      # Tables that have full Lutaml::Model parsing support
+      FULLY_PARSED_TABLES = %w[
+        head hhea maxp post OS/2 name
+        fvar HVAR VVAR MVAR cvar gvar
+      ].freeze
+
+      # Tables that should be stored as binary
+      BINARY_ONLY_TABLES = %w[
+        cvt fpgm prep gasp DSIG GDEF GPOS GSUB
+      ].freeze
+
+      # Initialize table serializer
+      #
+      # @param binary_format [Symbol] Format for binary data (:hex or :base64)
+      def initialize(binary_format: :hex)
+        @binary_format = binary_format
+        validate_binary_format!
+      end
+
+      # Serialize a table to exportable format
+      #
+      # @param table [Object] The table object
+      # @param tag [String] The table tag
+      # @return [Hash] Serialized table data
+      def serialize(table, tag)
+        if fully_parsed?(tag)
+          serialize_parsed(table, tag)
+        elsif binary_only?(tag)
+          serialize_binary(table.to_binary_s, tag)
+        else
+          serialize_mixed(table, tag)
+        end
+      end
+
+      # Serialize a parsed table
+      #
+      # @param table [Object] The table object with Lutaml::Model
+      # @param tag [String] The table tag
+      # @return [Hash] Serialized data with parsed flag
+      def serialize_parsed(table, tag)
+        fields = extract_fields(table)
+        {
+          tag: tag,
+          parsed: true,
+          fields: fields.to_json,
+          data: nil,
+        }
+      end
+
+      # Serialize a binary-only table
+      #
+      # @param data [String] Binary data
+      # @param tag [String] The table tag
+      # @return [Hash] Serialized data with binary content
+      def serialize_binary(data, tag)
+        encoded = encode_binary(data)
+        {
+          tag: tag,
+          parsed: false,
+          data: encoded,
+          fields: nil,
+        }
+      end
+
+      # Serialize tables with mixed content (summary + binary)
+      #
+      # @param table [Object] The table object
+      # @param tag [String] The table tag
+      # @return [Hash] Serialized data with both fields and binary
+      def serialize_mixed(table, tag)
+        summary = create_summary(table, tag)
+        binary = table.respond_to?(:to_binary_s) ? table.to_binary_s : ""
+
+        {
+          tag: tag,
+          parsed: true,
+          fields: summary.to_json,
+          data: encode_binary(binary),
+        }
+      end
+
+      private
+
+      # Check if table is fully parsed
+      #
+      # @param tag [String] Table tag
+      # @return [Boolean]
+      def fully_parsed?(tag)
+        FULLY_PARSED_TABLES.include?(tag)
+      end
+
+      # Check if table is binary-only
+      #
+      # @param tag [String] Table tag
+      # @return [Boolean]
+      def binary_only?(tag)
+        BINARY_ONLY_TABLES.include?(tag)
+      end
+
+      # Extract fields from a parsed table
+      #
+      # @param table [Object] The table object
+      # @return [Hash] Field names and values
+      def extract_fields(table)
+        fields = {}
+
+        # Get all instance variables
+        table.instance_variables.each do |var|
+          name = var.to_s.delete("@")
+          value = table.instance_variable_get(var)
+          fields[name] = serialize_value(value)
+        end
+
+        fields
+      end
+
+      # Serialize individual field value
+      #
+      # @param value [Object] The value to serialize
+      # @return [Object] Serialized value
+      def serialize_value(value)
+        case value
+        when Integer, Float, String, TrueClass, FalseClass, NilClass
+          value
+        when Array
+          value.map { |v| serialize_value(v) }
+        when Hash
+          value.transform_values { |v| serialize_value(v) }
+        when Time
+          value.iso8601
+        else
+          # For complex objects, try to extract fields
+          if value.respond_to?(:instance_variables)
+            extract_fields(value)
+          else
+            value.to_s
+          end
+        end
+      end
+
+      # Create summary for mixed-content tables
+      #
+      # @param table [Object] The table object
+      # @param tag [String] Table tag
+      # @return [Hash] Summary information
+      def create_summary(table, tag)
+        case tag
+        when "glyf"
+          create_glyf_summary(table)
+        when "loca"
+          create_loca_summary(table)
+        when "cmap"
+          create_cmap_summary(table)
+        when "CFF"
+          create_cff_summary(table)
+        else
+          { type: "binary", size: table.to_binary_s.bytesize }
+        end
+      end
+
+      # Create glyf table summary
+      #
+      # @param table [Object] glyf table
+      # @return [Hash] Summary
+      def create_glyf_summary(table)
+        {
+          type: "glyf",
+          num_glyphs: table.respond_to?(:glyphs) ? table.glyphs.length : 0,
+          note: "Outline data stored as binary",
+        }
+      end
+
+      # Create loca table summary
+      #
+      # @param table [Object] loca table
+      # @return [Hash] Summary
+      def create_loca_summary(table)
+        {
+          type: "loca",
+          num_offsets: table.respond_to?(:offsets) ? table.offsets.length : 0,
+          format: table.respond_to?(:format) ? table.format : nil,
+        }
+      end
+
+      # Create cmap table summary
+      #
+      # @param table [Object] cmap table
+      # @return [Hash] Summary
+      def create_cmap_summary(table)
+        {
+          type: "cmap",
+          version: table.respond_to?(:version) ? table.version : 0,
+          note: "Character mappings stored as binary",
+        }
+      end
+
+      # Create CFF table summary
+      #
+      # @param table [Object] CFF table
+      # @return [Hash] Summary
+      def create_cff_summary(_table)
+        {
+          type: "CFF",
+          note: "CharString data stored as binary",
+        }
+      end
+
+      # Encode binary data based on format
+      #
+      # @param data [String] Binary data
+      # @return [String] Encoded data
+      def encode_binary(data)
+        case @binary_format
+        when :hex
+          data.unpack1("H*")
+        when :base64
+          Base64.strict_encode64(data)
+        end
+      end
+
+      # Validate binary format option
+      #
+      # @raise [ArgumentError] if format is invalid
+      def validate_binary_format!
+        valid_formats = %i[hex base64]
+        return if valid_formats.include?(@binary_format)
+
+        raise ArgumentError,
+              "Invalid binary format: #{@binary_format}. " \
+              "Must be one of: #{valid_formats.join(', ')}"
+      end
+    end
+  end
+end

data/lib/fontisan/export/transformers/font_to_ttx.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative "../../models/ttx/ttfont"
+require_relative "../../models/ttx/glyph_order"
+require_relative "head_transformer"
+require_relative "name_transformer"
+require_relative "os2_transformer"
+require_relative "post_transformer"
+require_relative "hhea_transformer"
+require_relative "maxp_transformer"
+
+module Fontisan
+  module Export
+    module Transformers
+      # FontToTtx orchestrates font to TTX transformation
+      #
+      # Main transformer that coordinates conversion of a complete
+      # font to TTX format using individual table transformers.
+      # Follows model-to-model transformation principles with
+      # clean separation of concerns.
+      class FontToTtx
+        # Initialize transformer
+        #
+        # @param font [TrueTypeFont, OpenTypeFont] Source font
+        def initialize(font)
+          @font = font
+        end
+
+        # Transform font to TTX model
+        #
+        # @param options [Hash] Transformation options
+        # @option options [Array<String>] :tables Specific tables to include
+        # @return [Models::Ttx::TtFont] Complete TTX model
+        def transform(options = {})
+          table_list = options[:tables] || :all
+
+          Models::Ttx::TtFont.new.tap do |ttx|
+            ttx.sfnt_version = format_sfnt_version(@font.header.sfnt_version.to_i)
+            ttx.ttlib_version = "4.0"
+            ttx.glyph_order = build_glyph_order
+
+            # Transform specific tables
+            tables_to_transform = select_tables(table_list)
+            tables_to_transform.each do |tag|
+              transform_table(ttx, tag)
+            end
+          end
+        end
+
+        private
+
+        # Build glyph order model
+        #
+        # @return [Models::Ttx::GlyphOrder] Glyph order model
+        def build_glyph_order
+          Models::Ttx::GlyphOrder.new.tap do |glyph_order|
+            glyph_order.glyph_ids = build_glyph_ids
+          end
+        end
+
+        # Build glyph ID entries
+        #
+        # @return [Array<Models::Ttx::GlyphId>] Glyph ID models
+        def build_glyph_ids
+          Array.new(glyph_count) do |glyph_id|
+            Models::Ttx::GlyphId.new.tap do |gid|
+              gid.id = glyph_id
+              gid.name = get_glyph_name(glyph_id)
+            end
+          end
+        end
+
+        # Transform individual table
+        #
+        # @param ttx [Models::Ttx::TtFont] TTX model being built
+        # @param tag [String] Table tag
+        # @return [void]
+        def transform_table(ttx, tag)
+          table = @font.table(tag)
+          return unless table
+
+          case tag
+          when "head"
+            ttx.head_table = HeadTransformer.transform(table)
+          when "hhea"
+            ttx.hhea_table = HheaTransformer.transform(table)
+          when "maxp"
+            ttx.maxp_table = MaxpTransformer.transform(table)
+          when "name"
+            ttx.name_table = NameTransformer.transform(table)
+          when "OS/2"
+            ttx.os2_table = Os2Transformer.transform(table)
+          when "post"
+            ttx.post_table = PostTransformer.transform(table)
+          else
+            # Fallback to binary table
+            binary_table = transform_binary_table(tag, table)
+            ttx.binary_tables ||= []
+            ttx.binary_tables << binary_table if binary_table
+          end
+        rescue StandardError => e
+          # On error, fall back to binary representation
+          warn "Error transforming #{tag}: #{e.message}"
+          binary_table = transform_binary_table(tag, table)
+          ttx.binary_tables ||= []
+          ttx.binary_tables << binary_table if binary_table
+        end
+
+        # Transform table to binary representation
+        #
+        # @param tag [String] Table tag
+        # @param table [Object] Table object
+        # @return [Models::Ttx::Tables::BinaryTable, nil] Binary table model
+        def transform_binary_table(tag, table)
+          binary_data = table.respond_to?(:to_binary_s) ? table.to_binary_s : ""
+          return nil if binary_data.empty?
+
+          Models::Ttx::Tables::BinaryTable.new.tap do |bin_table|
+            bin_table.tag = tag
+            bin_table.hexdata = binary_data
+          end
+        end
+
+        # Select tables to transform
+        #
+        # @param table_list [Symbol, Array<String>] :all or list of tags
+        # @return [Array<String>] Table tags to transform
+        def select_tables(table_list)
+          if table_list == :all
+            @font.table_names
+          else
+            available = @font.table_names
+            requested = Array(table_list).map(&:to_s)
+            requested.select { |tag| available.include?(tag) }
+          end
+        end
+
+        # Get number of glyphs
+        #
+        # @return [Integer] Number of glyphs
+        def glyph_count
+          maxp = @font.table("maxp")
+          maxp ? maxp.num_glyphs.to_i : 0
+        end
+
+        # Get glyph name by ID
+        #
+        # @param glyph_id [Integer] Glyph ID
+        # @return [String] Glyph name
+        def get_glyph_name(glyph_id)
+          post = @font.table("post")
+          if post.respond_to?(:glyph_names) && post.glyph_names
+            post.glyph_names[glyph_id] || ".notdef"
+          elsif glyph_id.zero?
+            ".notdef"
+          else
+            "glyph#{glyph_id.to_s.rjust(5, '0')}"
+          end
+        end
+
+        # Format SFNT version
+        #
+        # @param version [Integer] SFNT version
+        # @return [String] Formatted version as escaped bytes
+        def format_sfnt_version(version)
+          bytes = [version].pack("N").bytes
+          "\\x#{bytes.map { |b| b.to_s(16).rjust(2, '0') }.join('\\x')}"
+        end
+      end
+    end
+  end
+end