fontisan 0.1.0 → 0.2.0

data/lib/fontisan/loading_modes.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Fontisan
+  # Loading modes module that defines which tables are loaded in each mode.
+  #
+  # This module provides a MECE (Mutually Exclusive, Collectively Exhaustive)
+  # architecture for font loading modes. Each mode defines a specific set of
+  # tables to load, enabling efficient parsing for different use cases.
+  #
+  # @example Using metadata mode
+  #   mode = LoadingModes::METADATA
+  #   tables = LoadingModes.tables_for(mode)  # => ["name", "head", "hhea", "maxp", "OS/2", "post"]
+  #
+  # @example Checking table availability
+  #   LoadingModes.table_allowed?(:metadata, "GSUB")  # => false
+  #   LoadingModes.table_allowed?(:full, "GSUB")      # => true
+  module LoadingModes
+    # Metadata mode: loads only tables needed for font identification and metrics
+    # Equivalent to otfinfo functionality
+    METADATA = :metadata
+
+    # Full mode: loads all tables in the font
+    FULL = :full
+
+    # Mode definitions with their respective table lists
+    MODES = {
+      METADATA => {
+        tables: %w[name head hhea maxp OS/2 post].freeze,
+        description: "Metadata mode - loads only identification and metrics tables (otfinfo-equivalent)"
+      }.freeze,
+      FULL => {
+        tables: :all,
+        description: "Full mode - loads all tables in the font"
+      }.freeze
+    }.freeze
+
+    # Pre-computed Set for O(1) lookup of metadata tables
+    # This constant avoids recreating the Set on every font load
+    METADATA_TABLES_SET = MODES[METADATA][:tables].to_set.freeze
+
+    # Get the list of tables allowed for a given mode
+    #
+    # @param mode [Symbol] The loading mode (:metadata or :full)
+    # @return [Array<String>, Symbol] Array of table tags or :all for full mode
+    # @raise [ArgumentError] if mode is invalid
+    def self.tables_for(mode)
+      validate_mode!(mode)
+      MODES[mode][:tables]
+    end
+
+    # Check if a table is allowed in a given mode
+    #
+    # @param mode [Symbol] The loading mode (:metadata or :full)
+    # @param tag [String] The table tag to check
+    # @return [Boolean] true if table is allowed in the mode
+    # @raise [ArgumentError] if mode is invalid
+    def self.table_allowed?(mode, tag)
+      validate_mode!(mode)
+
+      tables = MODES[mode][:tables]
+      return true if tables == :all
+
+      tables.include?(tag)
+    end
+
+    # Validate that a mode is valid
+    #
+    # @param mode [Symbol] The mode to validate
+    # @return [Boolean] true if mode is valid
+    def self.valid_mode?(mode)
+      MODES.key?(mode)
+    end
+
+    # Get the default lazy loading setting for a mode
+    #
+    # @param mode [Symbol] The loading mode
+    # @return [Boolean] true if lazy loading is recommended for this mode
+    # @raise [ArgumentError] if mode is invalid
+    def self.default_lazy?(mode)
+      validate_mode!(mode)
+      true  # Lazy loading is recommended for all modes
+    end
+
+    # Get mode description
+    #
+    # @param mode [Symbol] The loading mode
+    # @return [String] Description of the mode
+    # @raise [ArgumentError] if mode is invalid
+    def self.description(mode)
+      validate_mode!(mode)
+      MODES[mode][:description]
+    end
+
+    # Get all available modes
+    #
+    # @return [Array<Symbol>] List of all mode symbols
+    def self.all_modes
+      MODES.keys
+    end
+
+    # Validate mode and raise error if invalid
+    #
+    # @param mode [Symbol] The mode to validate
+    # @return [void]
+    # @raise [ArgumentError] if mode is invalid
+    def self.validate_mode!(mode)
+      return if valid_mode?(mode)
+
+      raise ArgumentError,
+            "Invalid mode: #{mode.inspect}. Valid modes are: #{all_modes.map(&:inspect).join(', ')}"
+    end
+  end
+end

data/lib/fontisan/metrics_calculator.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+
+module Fontisan
+  # High-level utility class for accessing font metrics
+  #
+  # MetricsCalculator provides a convenient API for querying font metrics from
+  # multiple OpenType tables without needing to work with the low-level table
+  # structures directly. It wraps access to hhea, hmtx, head, maxp, and cmap
+  # tables.
+  #
+  # The calculator handles missing tables gracefully and provides both
+  # individual glyph metrics and string-level calculations.
+  #
+  # @example Basic usage
+  #   font = FontLoader.from_file("path/to/font.ttf")
+  #   calc = MetricsCalculator.new(font)
+  #
+  #   puts calc.ascent          # => 2048
+  #   puts calc.descent         # => -512
+  #   puts calc.line_height     # => 2650
+  #   puts calc.units_per_em    # => 2048
+  #
+  # @example Glyph metrics
+  #   width = calc.glyph_width(42)
+  #   lsb = calc.glyph_left_side_bearing(42)
+  #
+  # @example String width calculation
+  #   width = calc.string_width("Hello")
+  #
+  # @example Checking for metrics support
+  #   if calc.has_metrics?
+  #     puts "Font has complete horizontal metrics"
+  #   end
+  class MetricsCalculator
+    # The font object this calculator operates on
+    #
+    # @return [OpenTypeFont, TrueTypeFont] The font instance
+    attr_reader :font
+
+    # Initialize a new MetricsCalculator
+    #
+    # @param font [OpenTypeFont, TrueTypeFont] Font instance to calculate metrics for
+    # @raise [ArgumentError] if font is nil
+    def initialize(font)
+      raise ArgumentError, "Font cannot be nil" if font.nil?
+
+      @font = font
+      @hhea_table = nil
+      @hmtx_table = nil
+      @head_table = nil
+      @maxp_table = nil
+      @cmap_table = nil
+      @hmtx_parsed = false
+    end
+
+    # Get typographic ascent from hhea table
+    #
+    # The ascent is the distance from the baseline to the highest ascender.
+    # It is a positive value in font units (FUnits).
+    #
+    # @return [Integer, nil] Ascent value in FUnits, or nil if hhea table is missing
+    #
+    # @example
+    #   calc.ascent # => 2048
+    def ascent
+      hhea&.ascent
+    end
+
+    # Get typographic descent from hhea table
+    #
+    # The descent is the distance from the baseline to the lowest descender.
+    # It is typically a negative value in font units (FUnits).
+    #
+    # @return [Integer, nil] Descent value in FUnits, or nil if hhea table is missing
+    #
+    # @example
+    #   calc.descent # => -512
+    def descent
+      hhea&.descent
+    end
+
+    # Get line gap from hhea table
+    #
+    # The line gap is additional vertical space between lines of text.
+    # It is a non-negative value in font units (FUnits).
+    #
+    # @return [Integer, nil] Line gap value in FUnits, or nil if hhea table is missing
+    #
+    # @example
+    #   calc.line_gap # => 90
+    def line_gap
+      hhea&.line_gap
+    end
+
+    # Get units per em from head table
+    #
+    # This value defines the font's coordinate system scale. Common values
+    # are 1000 (PostScript fonts) or 2048 (TrueType fonts).
+    #
+    # @return [Integer, nil] Units per em value, or nil if head table is missing
+    #
+    # @example
+    #   calc.units_per_em # => 2048
+    def units_per_em
+      head&.units_per_em
+    end
+
+    # Get advance width for a specific glyph
+    #
+    # The advance width is the horizontal distance to advance the pen position
+    # after rendering this glyph. It is in font units (FUnits).
+    #
+    # @param glyph_id [Integer] The glyph ID (0-based)
+    # @return [Integer, nil] Advance width in FUnits, or nil if not available
+    #
+    # @example
+    #   calc.glyph_width(42) # => 1234
+    def glyph_width(glyph_id)
+      ensure_hmtx_parsed
+      return nil unless hmtx
+
+      metric = hmtx.metric_for(glyph_id)
+      metric&.dig(:advance_width)
+    end
+
+    # Alias for {#glyph_width}
+    #
+    # @param glyph_id [Integer] The glyph ID (0-based)
+    # @return [Integer, nil] Advance width in FUnits, or nil if not available
+    alias glyph_advance_width glyph_width
+
+    # Get left side bearing for a specific glyph
+    #
+    # The left side bearing (LSB) is the horizontal distance from the pen
+    # position to the leftmost point of the glyph. It can be negative if
+    # the glyph extends to the left of the pen position.
+    #
+    # @param glyph_id [Integer] The glyph ID (0-based)
+    # @return [Integer, nil] Left side bearing in FUnits, or nil if not available
+    #
+    # @example
+    #   calc.glyph_left_side_bearing(42) # => 50
+    def glyph_left_side_bearing(glyph_id)
+      ensure_hmtx_parsed
+      return nil unless hmtx
+
+      metric = hmtx.metric_for(glyph_id)
+      metric&.dig(:lsb)
+    end
+
+    # Calculate total width for a string
+    #
+    # Calculates the sum of advance widths for all characters in the string.
+    # This is a simplified calculation that does not account for kerning,
+    # ligatures, or other advanced typography features.
+    #
+    # Characters not mapped in the font are skipped.
+    #
+    # @param string [String] The string to measure
+    # @return [Integer, nil] Total width in FUnits, or nil if metrics unavailable
+    #
+    # @example
+    #   calc.string_width("Hello") # => 5420
+    def string_width(string)
+      return nil unless has_metrics?
+      return 0 if string.nil? || string.empty?
+
+      total_width = 0
+      string.each_codepoint do |codepoint|
+        glyph_id = codepoint_to_glyph_id(codepoint)
+        next unless glyph_id
+
+        width = glyph_width(glyph_id)
+        total_width += width if width
+      end
+
+      total_width
+    end
+
+    # Calculate line height
+    #
+    # Line height is calculated as: ascent - descent + line_gap
+    # This represents the recommended spacing between consecutive baselines.
+    #
+    # @return [Integer, nil] Line height in FUnits, or nil if hhea table is missing
+    #
+    # @example
+    #   calc.line_height # => 2650 (when ascent=2048, descent=-512, line_gap=90)
+    def line_height
+      return nil unless hhea
+
+      ascent - descent + line_gap
+    end
+
+    # Alias for {#units_per_em}
+    #
+    # @return [Integer, nil] Units per em value, or nil if head table is missing
+    alias em_height units_per_em
+
+    # Check if font has complete horizontal metrics
+    #
+    # Returns true if the font has all required tables for horizontal metrics:
+    # hhea, hmtx, head, and maxp tables.
+    #
+    # @return [Boolean] True if all metrics tables are present
+    #
+    # @example
+    #   calc.has_metrics? # => true
+    def has_metrics?
+      !hhea.nil? && !hmtx.nil? && !head.nil? && !maxp.nil?
+    end
+
+    private
+
+    # Get hhea table, caching the result
+    #
+    # @return [Tables::Hhea, nil] The hhea table or nil
+    def hhea
+      @hhea ||= font.table(Constants::HHEA_TAG)
+    end
+
+    # Get hmtx table, caching the result
+    #
+    # @return [Tables::Hmtx, nil] The hmtx table or nil
+    def hmtx
+      @hmtx ||= font.table(Constants::HMTX_TAG)
+    end
+
+    # Get head table, caching the result
+    #
+    # @return [Tables::Head, nil] The head table or nil
+    def head
+      @head ||= font.table(Constants::HEAD_TAG)
+    end
+
+    # Get maxp table, caching the result
+    #
+    # @return [Tables::Maxp, nil] The maxp table or nil
+    def maxp
+      @maxp ||= font.table(Constants::MAXP_TAG)
+    end
+
+    # Get cmap table, caching the result
+    #
+    # @return [Tables::Cmap, nil] The cmap table or nil
+    def cmap
+      @cmap ||= font.table(Constants::CMAP_TAG)
+    end
+
+    # Ensure hmtx table is parsed with context
+    #
+    # The hmtx table requires numberOfHMetrics from hhea and numGlyphs from maxp
+    # to be parsed correctly. This method ensures parsing happens lazily on first use.
+    #
+    # @return [void]
+    def ensure_hmtx_parsed
+      return if @hmtx_parsed
+      return unless hmtx && hhea && maxp
+
+      hmtx.parse_with_context(hhea.number_of_h_metrics, maxp.num_glyphs)
+      @hmtx_parsed = true
+    end
+
+    # Map Unicode codepoint to glyph ID using cmap table
+    #
+    # @param codepoint [Integer] Unicode codepoint
+    # @return [Integer, nil] Glyph ID or nil if not mapped
+    def codepoint_to_glyph_id(codepoint)
+      return nil unless cmap
+
+      mappings = cmap.unicode_mappings
+      mappings[codepoint]
+    end
+  end
+end

data/lib/fontisan/models/collection_font_summary.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    # Model for individual font summary within a collection
+    #
+    # Represents basic metadata for a single font in a TTC/OTC collection.
+    # Used by CollectionListInfo to provide per-font summaries.
+    #
+    # @example Creating a font summary
+    #   summary = CollectionFontSummary.new(
+    #     index: 0,
+    #     family_name: "Helvetica",
+    #     subfamily_name: "Regular",
+    #     postscript_name: "Helvetica-Regular",
+    #     font_format: "TrueType",
+    #     num_glyphs: 268,
+    #     num_tables: 14
+    #   )
+    class CollectionFontSummary < Lutaml::Model::Serializable
+      attribute :index, :integer
+      attribute :family_name, :string
+      attribute :subfamily_name, :string
+      attribute :postscript_name, :string
+      attribute :font_format, :string
+      attribute :num_glyphs, :integer
+      attribute :num_tables, :integer
+
+      yaml do
+        map "index", to: :index
+        map "family_name", to: :family_name
+        map "subfamily_name", to: :subfamily_name
+        map "postscript_name", to: :postscript_name
+        map "font_format", to: :font_format
+        map "num_glyphs", to: :num_glyphs
+        map "num_tables", to: :num_tables
+      end
+
+      json do
+        map "index", to: :index
+        map "family_name", to: :family_name
+        map "subfamily_name", to: :subfamily_name
+        map "postscript_name", to: :postscript_name
+        map "font_format", to: :font_format
+        map "num_glyphs", to: :num_glyphs
+        map "num_tables", to: :num_tables
+      end
+    end
+  end
+end

data/lib/fontisan/models/collection_info.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "table_sharing_info"
+
+module Fontisan
+  module Models
+    # Model for collection metadata
+    #
+    # Represents comprehensive information about a TTC/OTC collection.
+    # Used by InfoCommand when operating on collection files.
+    #
+    # @example Creating collection info
+    #   info = CollectionInfo.new(
+    #     collection_path: "fonts.ttc",
+    #     collection_format: "TTC",
+    #     ttc_tag: "ttcf",
+    #     major_version: 2,
+    #     minor_version: 0,
+    #     num_fonts: 6,
+    #     font_offsets: [48, 380, 712, 1044, 1376, 1676],
+    #     file_size_bytes: 2240000,
+    #     table_sharing: table_sharing_obj
+    #   )
+    class CollectionInfo < Lutaml::Model::Serializable
+      attribute :collection_path, :string
+      attribute :collection_format, :string
+      attribute :ttc_tag, :string
+      attribute :major_version, :integer
+      attribute :minor_version, :integer
+      attribute :num_fonts, :integer
+      attribute :font_offsets, :integer, collection: true
+      attribute :file_size_bytes, :integer
+      attribute :table_sharing, TableSharingInfo
+
+      yaml do
+        map "collection_path", to: :collection_path
+        map "collection_format", to: :collection_format
+        map "ttc_tag", to: :ttc_tag
+        map "major_version", to: :major_version
+        map "minor_version", to: :minor_version
+        map "num_fonts", to: :num_fonts
+        map "font_offsets", to: :font_offsets
+        map "file_size_bytes", to: :file_size_bytes
+        map "table_sharing", to: :table_sharing
+      end
+
+      json do
+        map "collection_path", to: :collection_path
+        map "collection_format", to: :collection_format
+        map "ttc_tag", to: :ttc_tag
+        map "major_version", to: :major_version
+        map "minor_version", to: :minor_version
+        map "num_fonts", to: :num_fonts
+        map "font_offsets", to: :font_offsets
+        map "file_size_bytes", to: :file_size_bytes
+        map "table_sharing", to: :table_sharing
+      end
+
+      # Get version as a formatted string
+      #
+      # @return [String] Version string (e.g., "2.0")
+      def version_string
+        "#{major_version}.#{minor_version}"
+      end
+
+      # Get version as a hexadecimal string
+      #
+      # @return [String] Hex version (e.g., "0x00020000")
+      def version_hex
+        version_int = (major_version << 16) | minor_version
+        format("0x%08X", version_int)
+      end
+    end
+  end
+end

data/lib/fontisan/models/collection_list_info.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "collection_font_summary"
+
+module Fontisan
+  module Models
+    # Model for collection font listing
+    #
+    # Represents a list of fonts within a TTC/OTC collection.
+    # Used by LsCommand when operating on collection files.
+    #
+    # @example Creating a collection list
+    #   list = CollectionListInfo.new(
+    #     collection_path: "fonts.ttc",
+    #     num_fonts: 6,
+    #     fonts: [summary1, summary2, ...]
+    #   )
+    class CollectionListInfo < Lutaml::Model::Serializable
+      attribute :collection_path, :string
+      attribute :num_fonts, :integer
+      attribute :fonts, CollectionFontSummary, collection: true
+
+      yaml do
+        map "collection_path", to: :collection_path
+        map "num_fonts", to: :num_fonts
+        map "fonts", to: :fonts
+      end
+
+      json do
+        map "collection_path", to: :collection_path
+        map "num_fonts", to: :num_fonts
+        map "fonts", to: :fonts
+      end
+    end
+  end
+end