fontisan 0.1.0

data/lib/fontisan/config/scripts.yml

@@ -0,0 +1,42 @@
+# OpenType script tags and descriptions
+# Reference: OpenType specification
+arab: Arabic
+armn: Armenian
+beng: Bengali
+bopo: Bopomofo
+brai: Braille
+byzm: Byzantine Musical Symbols
+cans: Canadian Aboriginal Syllabics
+cher: Cherokee
+cyrl: Cyrillic
+DFLT: Default
+deva: Devanagari
+ethi: Ethiopic
+geor: Georgian
+goth: Gothic
+grek: Greek
+gujr: Gujarati
+guru: Gurmukhi
+hang: Hangul
+hani: Han Ideographs
+hebr: Hebrew
+hira: Hiragana
+kana: Katakana
+khmr: Khmer
+knda: Kannada
+lao: Lao
+latn: Latin
+math: Mathematical Alphanumeric Symbols
+mlym: Malayalam
+mong: Mongolian
+mymr: Myanmar
+ogam: Ogham
+orya: Oriya
+runr: Runic
+sinh: Sinhala
+syrc: Syriac
+taml: Tamil
+telu: Telugu
+thaa: Thaana
+thai: Thai
+tibt: Tibetan

data/lib/fontisan/constants.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Fontisan
+  # Constants module containing immutable constant definitions for font file operations.
+  #
+  # This module defines all magic numbers, version identifiers, and file format constants
+  # used throughout the fontisan gem. These values are based on the TrueType Collection,
+  # TrueType Font, and OpenType Font specifications.
+  module Constants
+    # TrueType Collection file signature tag.
+    # All valid TTC files must begin with this 4-byte tag.
+    TTC_TAG = "ttcf"
+
+    # TrueType Collection Version 1.0 identifier.
+    # Represents the original TTC format version.
+    TTC_VERSION_1 = 0x00010000
+
+    # TrueType Collection Version 2.0 identifier.
+    # Represents the extended TTC format with digital signature support.
+    TTC_VERSION_2 = 0x00020000
+
+    # SFNT version for TrueType fonts
+    SFNT_VERSION_TRUETYPE = 0x00010000
+
+    # SFNT version for OpenType fonts with CFF outlines ('OTTO')
+    SFNT_VERSION_OTTO = 0x4F54544F
+
+    # Head table tag identifier.
+    # The 'head' table contains global font header information including
+    # the checksum adjustment field.
+    HEAD_TAG = "head"
+
+    # Name table tag identifier
+    NAME_TAG = "name"
+
+    # OS/2 table tag identifier
+    OS2_TAG = "OS/2"
+
+    # Post table tag identifier
+    POST_TAG = "post"
+
+    # Cmap table tag identifier
+    CMAP_TAG = "cmap"
+
+    # Glyf table tag identifier (TrueType glyph data)
+    GLYF_TAG = "glyf"
+
+    # Loca table tag identifier (TrueType glyph index to location)
+    LOCA_TAG = "loca"
+
+    # CFF table tag identifier (OpenType CFF glyph data)
+    CFF_TAG = "CFF "
+
+    # GSUB table tag identifier (Glyph Substitution)
+    GSUB_TAG = "GSUB"
+
+    # GPOS table tag identifier (Glyph Positioning)
+    GPOS_TAG = "GPOS"
+
+    # Fvar table tag identifier (Font Variations)
+    FVAR_TAG = "fvar"
+
+    # Magic number used for font file checksum adjustment calculation.
+    # This constant is used in conjunction with the file checksum to compute
+    # the checksumAdjustment value stored in the 'head' table.
+    # Formula: checksumAdjustment = CHECKSUM_ADJUSTMENT_MAGIC - file_checksum
+    CHECKSUM_ADJUSTMENT_MAGIC = 0xB1B0AFBA
+
+    # Supported TTC version numbers.
+    # An array of valid version identifiers for TrueType Collection files.
+    SUPPORTED_VERSIONS = [TTC_VERSION_1, TTC_VERSION_2].freeze
+
+    # Table data alignment boundary in bytes.
+    # All table data in TTF files must be aligned to 4-byte boundaries,
+    # with padding added as necessary.
+    TABLE_ALIGNMENT = 4
+  end
+end

data/lib/fontisan/error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Fontisan
+  class Error < StandardError; end
+
+  class InvalidFontError < Error; end
+
+  class UnsupportedFormatError < Error; end
+
+  class CorruptedTableError < Error; end
+
+  class MissingTableError < Error; end
+
+  class ParseError < Error; end
+end

data/lib/fontisan/font_loader.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+require_relative "true_type_font"
+require_relative "open_type_font"
+require_relative "true_type_collection"
+require_relative "open_type_collection"
+require_relative "error"
+
+module Fontisan
+  # FontLoader provides unified font loading with automatic format detection.
+  #
+  # This class is the primary entry point for loading fonts in Fontisan.
+  # It automatically detects the font format and returns the appropriate
+  # domain object (TrueTypeFont, OpenTypeFont, TrueTypeCollection, or OpenTypeCollection).
+  #
+  # @example Load any font type
+  #   font = FontLoader.load("font.ttf")  # => TrueTypeFont
+  #   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)
+  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
+    # @raise [Errno::ENOENT] if file does not exist
+    # @raise [UnsupportedFormatError] for WOFF/WOFF2 or other unsupported formats
+    # @raise [InvalidFontError] for corrupted or unknown formats
+    def self.load(path, font_index: 0)
+      raise Errno::ENOENT, "File not found: #{path}" unless File.exist?(path)
+
+      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)
+        when pack_uint32(Constants::SFNT_VERSION_TRUETYPE)
+          TrueTypeFont.from_file(path)
+        when "OTTO"
+          OpenTypeFont.from_file(path)
+        when "wOFF"
+          raise UnsupportedFormatError,
+                "Unsupported font format: WOFF. Fontisan currently supports TTF, OTF, TTC, and OTC files."
+        when "wOF2"
+          raise UnsupportedFormatError,
+                "Unsupported font format: WOFF2. Fontisan currently supports TTF, OTF, TTC, and OTC files."
+        else
+          raise InvalidFontError,
+                "Unknown font format. Expected TTF, OTF, TTC, or OTC file."
+        end
+      end
+    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
+    # @return [TrueTypeFont, OpenTypeFont] The loaded font object
+    # @raise [InvalidFontError] if collection type cannot be determined
+    def self.load_from_collection(io, path, font_index)
+      # 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")
+
+      if font_index >= num_fonts
+        raise InvalidFontError,
+              "Font index #{font_index} out of range (collection has #{num_fonts} fonts)"
+      end
+
+      # Read first offset to detect collection type
+      first_offset = io.read(4).unpack1("N")
+
+      # Peek at first font's sfnt_version to determine TTC vs OTC
+      io.seek(first_offset)
+      sfnt_version = io.read(4).unpack1("N")
+      io.rewind
+
+      case sfnt_version
+      when Constants::SFNT_VERSION_TRUETYPE
+        # TrueType Collection
+        ttc = TrueTypeCollection.from_file(path)
+        File.open(path, "rb") { |f| ttc.font(font_index, f) }
+      when Constants::SFNT_VERSION_OTTO
+        # OpenType Collection
+        otc = OpenTypeCollection.from_file(path)
+        File.open(path, "rb") { |f| otc.font(font_index, f) }
+      else
+        raise InvalidFontError,
+              "Unknown font type in collection (sfnt version: 0x#{sfnt_version.to_s(16)})"
+      end
+    end
+
+    # Pack uint32 value to big-endian bytes
+    #
+    # @param value [Integer] The uint32 value
+    # @return [String] 4-byte binary string
+    # @api private
+    def self.pack_uint32(value)
+      [value].pack("N")
+    end
+
+    private_class_method :load_from_collection, :pack_uint32
+  end
+end

data/lib/fontisan/formatters/text_formatter.rb

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Formatters
+    # TextFormatter formats model objects into human-readable text output.
+    #
+    # This formatter handles Models::FontInfo and Models::TableInfo objects,
+    # presenting them with proper alignment and spacing for terminal display.
+    #
+    # @example Format font information
+    #   formatter = TextFormatter.new
+    #   text = formatter.format(font_info)
+    #   puts text
+    class TextFormatter
+      # Format a model object into human-readable text.
+      #
+      # @param model [Object] The model to format (FontInfo, TableInfo, etc.)
+      # @return [String] Formatted text representation
+      def format(model)
+        case model
+        when Models::FontInfo
+          format_font_info(model)
+        when Models::TableInfo
+          format_table_info(model)
+        when Models::GlyphInfo
+          format_glyph_info(model)
+        when Models::UnicodeMappings
+          format_unicode_mappings(model)
+        when Models::VariableFontInfo
+          format_variable_font_info(model)
+        when Models::OpticalSizeInfo
+          format_optical_size_info(model)
+        when Models::ScriptsInfo
+          format_scripts_info(model)
+        when Models::AllScriptsFeaturesInfo
+          format_all_scripts_features_info(model)
+        when Models::FeaturesInfo
+          format_features_info(model)
+        else
+          model.to_s
+        end
+      end
+
+      private
+
+      # Format FontInfo as human-readable text.
+      #
+      # @param info [Models::FontInfo] Font information to format
+      # @return [String] Formatted text with aligned labels and values
+      def format_font_info(info)
+        lines = []
+
+        # Font type should be first (formatted for display)
+        font_type_display = format_font_type_display(info.font_format,
+                                                     info.is_variable)
+        add_line(lines, "Font type", font_type_display)
+
+        add_line(lines, "Family", info.family_name)
+        add_line(lines, "Subfamily", info.subfamily_name)
+        add_line(lines, "Full name", info.full_name)
+        add_line(lines, "PostScript name", info.postscript_name)
+        add_line(lines, "PostScript CID name", info.postscript_cid_name)
+        add_line(lines, "Preferred family", info.preferred_family)
+        add_line(lines, "Preferred subfamily", info.preferred_subfamily)
+        add_line(lines, "Mac font menu name", info.mac_font_menu_name)
+        add_line(lines, "Version", info.version)
+        add_line(lines, "Unique ID", info.unique_id)
+        add_line(lines, "Description", info.description)
+        add_line(lines, "Designer", info.designer)
+        add_line(lines, "Designer URL", info.designer_url)
+        add_line(lines, "Manufacturer", info.manufacturer)
+        add_line(lines, "Vendor URL", info.vendor_url)
+        add_line(lines, "Vendor ID", info.vendor_id)
+        add_line(lines, "Trademark", info.trademark)
+        add_line(lines, "Copyright", info.copyright)
+        add_line(lines, "License Description", info.license_description)
+        add_line(lines, "License URL", info.license_url)
+        add_line(lines, "Sample text", info.sample_text)
+        add_line(lines, "Font revision", format_float(info.font_revision))
+        add_line(lines, "Permissions", info.permissions)
+        add_line(lines, "Units per em", info.units_per_em)
+
+        lines.join("\n")
+      end
+
+      # Format TableInfo as human-readable text.
+      #
+      # @param info [Models::TableInfo] Table information to format
+      # @return [String] Formatted text with table directory listing
+      def format_table_info(info)
+        lines = []
+        lines << "SFNT Version: #{info.sfnt_version}"
+        lines << "Number of tables: #{info.num_tables}"
+        lines << ""
+        lines << "Tables:"
+
+        # Find max tag length for alignment
+        max_tag_len = info.tables.map { |t| t.tag.length }.max || 4
+
+        info.tables.each do |table|
+          tag = table.tag.ljust(max_tag_len)
+          lines << Kernel.format("  %<tag>s  %<length>10d bytes  (offset: %<offset>d, checksum: 0x%<checksum>08X)",
+                                 tag: tag, length: table.length, offset: table.offset, checksum: table.checksum)
+        end
+
+        lines.join("\n")
+      end
+
+      # Format GlyphInfo as human-readable text.
+      #
+      # @param info [Models::GlyphInfo] Glyph information to format
+      # @return [String] Formatted text with glyph names
+      def format_glyph_info(info)
+        lines = []
+
+        if info.glyph_names.empty?
+          lines << "No glyph name information available"
+          lines << "Source: #{info.source}"
+        else
+          lines << "Glyph count: #{info.glyph_count}"
+          lines << "Source: #{info.source}"
+          lines << ""
+          lines << "Glyph names:"
+
+          info.glyph_names.each_with_index do |name, index|
+            lines << Kernel.format("  %5d  %s", index, name)
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      # Format UnicodeMappings as human-readable text.
+      #
+      # @param mappings [Models::UnicodeMappings] Unicode mappings to format
+      # @return [String] Formatted text with Unicode to glyph mappings
+      def format_unicode_mappings(mappings)
+        lines = []
+
+        if mappings.mappings.empty?
+          lines << "No Unicode mappings available"
+        else
+          lines << "Unicode mappings: #{mappings.count}"
+          lines << ""
+
+          mappings.mappings.each do |mapping|
+            lines << if mapping.glyph_name
+                       "#{mapping.codepoint}  glyph #{mapping.glyph_index}  #{mapping.glyph_name}"
+                     else
+                       "#{mapping.codepoint}  glyph #{mapping.glyph_index}"
+                     end
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      # Format VariableFontInfo as human-readable text.
+      #
+      # @param info [Models::VariableFontInfo] Variable font information to format
+      # @return [String] Formatted text with axes and instances
+      def format_variable_font_info(info)
+        lines = []
+
+        unless info.is_variable
+          lines << "Not a variable font"
+          return lines.join("\n")
+        end
+
+        info.axes.each_with_index do |axis, i|
+          lines << "Axis #{i}:                 #{axis.tag}"
+          lines << "Axis #{i} name:            #{axis.name}" if axis.name
+          lines << "Axis #{i} range:           #{format_float(axis.min_value)} #{format_float(axis.max_value)}"
+          lines << "Axis #{i} default:         #{format_float(axis.default_value)}"
+        end
+
+        info.instances.each_with_index do |instance, i|
+          lines << "Instance #{i} name:        #{instance.name}"
+          coordinates = instance.coordinates.map do |c|
+            format_float(c)
+          end.join(" ")
+          lines << "Instance #{i} position:    #{coordinates}"
+        end
+
+        lines.join("\n")
+      end
+
+      # Format OpticalSizeInfo as human-readable text.
+      #
+      # @param info [Models::OpticalSizeInfo] Optical size information to format
+      # @return [String] Formatted text with optical size range
+      def format_optical_size_info(info)
+        return "No optical size information" unless info.has_optical_size
+
+        "Size range: [#{format_float(info.lower_point_size)}, #{format_float(info.upper_point_size)}) pt  (source: #{info.source})"
+      end
+
+      # Format ScriptsInfo as human-readable text.
+      #
+      # @param info [Models::ScriptsInfo] Scripts information to format
+      # @return [String] Formatted text with script tags and descriptions
+      def format_scripts_info(info)
+        lines = []
+
+        if info.scripts.empty?
+          lines << "No scripts found"
+        else
+          lines << "Script count: #{info.script_count}"
+          lines << ""
+
+          info.scripts.each do |script|
+            lines << "#{script.tag}  #{script.description}"
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      # Format AllScriptsFeaturesInfo as human-readable text.
+      #
+      # @param info [Models::AllScriptsFeaturesInfo] All scripts features information to format
+      # @return [String] Formatted text with features for all scripts
+      def format_all_scripts_features_info(info)
+        lines = []
+
+        info.scripts_features.each_with_index do |script_features, index|
+          lines << "" if index.positive? # Add blank line between scripts
+          lines << "Script: #{script_features.script}"
+          lines << "Feature count: #{script_features.feature_count}"
+          lines << ""
+
+          if script_features.features.empty?
+            lines << "  No features found"
+          else
+            script_features.features.each do |feature|
+              lines << "  #{feature.tag}  #{feature.description}"
+            end
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      # Format FeaturesInfo as human-readable text.
+      #
+      # @param info [Models::FeaturesInfo] Features information to format
+      # @return [String] Formatted text with feature tags and descriptions
+      def format_features_info(info)
+        lines = []
+
+        if info.features.empty?
+          lines << "No features found for script '#{info.script}'"
+        else
+          lines << "Script: #{info.script}"
+          lines << "Feature count: #{info.feature_count}"
+          lines << ""
+
+          info.features.each do |feature|
+            lines << "#{feature.tag}  #{feature.description}"
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      # Add a formatted line to the output if the value is present.
+      #
+      # @param lines [Array<String>] Output lines array
+      # @param label [String] Field label
+      # @param value [Object] Field value (skipped if nil or empty string)
+      def add_line(lines, label, value)
+        return if value.nil? || (value.is_a?(String) && value.empty?)
+
+        formatted_label = "#{label}:".ljust(25)
+        lines << "#{formatted_label} #{value}"
+      end
+
+      # Format a float value for display.
+      #
+      # @param value [Float, nil] Float value to format
+      # @return [String, nil] Formatted float or nil if input is nil
+      def format_float(value)
+        return nil if value.nil?
+
+        # Format to 5 decimal places, remove trailing zeros
+        formatted = Kernel.format("%<value>.5f", value: value)
+        formatted.sub(/\.?0+$/, "")
+      end
+
+      # Format font type for human-readable display.
+      #
+      # @param font_format [String] Enumerated font format code
+      # @param is_variable [Boolean] Whether font is variable
+      # @return [String, nil] Formatted font type or nil if font_format is nil
+      def format_font_type_display(font_format, is_variable)
+        return nil if font_format.nil?
+
+        type = case font_format
+               when "truetype"
+                 "TrueType"
+               when "cff"
+                 "OpenType (CFF)"
+               when "unknown"
+                 "Unknown"
+               else
+                 font_format
+               end
+
+        type += " (Variable)" if is_variable
+        type
+      end
+    end
+  end
+end

data/lib/fontisan/models/all_scripts_features_info.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "features_info"
+
+module Fontisan
+  module Models
+    # Represents features information for all scripts from GSUB/GPOS tables
+    class AllScriptsFeaturesInfo < Lutaml::Model::Serializable
+      attribute :scripts_features, FeaturesInfo, collection: true
+
+      json do
+        map "scripts_features", to: :scripts_features
+      end
+
+      yaml do
+        map "scripts_features", to: :scripts_features
+      end
+    end
+  end
+end

data/lib/fontisan/models/features_info.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    # Represents a single feature record
+    class FeatureRecord < Lutaml::Model::Serializable
+      attribute :tag, :string
+      attribute :description, :string
+
+      json do
+        map "tag", to: :tag
+        map "description", to: :description
+      end
+
+      yaml do
+        map "tag", to: :tag
+        map "description", to: :description
+      end
+    end
+
+    # Represents features information from GSUB/GPOS tables
+    class FeaturesInfo < Lutaml::Model::Serializable
+      attribute :script, :string
+      attribute :feature_count, :integer
+      attribute :features, FeatureRecord, collection: true
+
+      json do
+        map "script", to: :script
+        map "feature_count", to: :feature_count
+        map "features", to: :features
+      end
+
+      yaml do
+        map "script", to: :script
+        map "feature_count", to: :feature_count
+        map "features", to: :features
+      end
+    end
+  end
+end