fontisan 0.2.1 → 0.2.3

data/lib/fontisan/base_collection.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+require "bindata"
+require_relative "constants"
+
+module Fontisan
+  # Abstract base class for font collections (TTC/OTC)
+  #
+  # This class implements the shared logic for TrueTypeCollection and OpenTypeCollection
+  # using the Template Method pattern. Subclasses must implement the abstract methods
+  # to specify their font class and collection format.
+  #
+  # The BinData structure definition is shared between both collection types since
+  # both TTC and OTC files use the same "ttcf" tag and binary format. The only
+  # differences are:
+  # 1. The type of fonts contained (TrueType vs OpenType)
+  # 2. The format string used for display ("TTC" vs "OTC")
+  #
+  # @abstract Subclass and override {font_class} and {collection_format}
+  #
+  # @example Implementing a collection subclass
+  #   class TrueTypeCollection < BaseCollection
+  #     def self.font_class
+  #       TrueTypeFont
+  #     end
+  #
+  #     def self.collection_format
+  #       "TTC"
+  #     end
+  #   end
+  class BaseCollection < BinData::Record
+    endian :big
+
+    string :tag, length: 4, assert: "ttcf"
+    uint16 :major_version
+    uint16 :minor_version
+    uint32 :num_fonts
+    array :font_offsets, type: :uint32, initial_length: :num_fonts
+
+    # Abstract method: Get the font class for this collection type
+    #
+    # Subclasses must override this to return their specific font class
+    # (TrueTypeFont or OpenTypeFont).
+    #
+    # @return [Class] The font class (TrueTypeFont or OpenTypeFont)
+    # @raise [NotImplementedError] if not overridden by subclass
+    def self.font_class
+      raise NotImplementedError,
+            "#{name} must implement self.font_class"
+    end
+
+    # Abstract method: Get the collection format string
+    #
+    # Subclasses must override this to return "TTC" or "OTC".
+    #
+    # @return [String] Collection format ("TTC" or "OTC")
+    # @raise [NotImplementedError] if not overridden by subclass
+    def self.collection_format
+      raise NotImplementedError,
+            "#{name} must implement self.collection_format"
+    end
+
+    # Read collection from a file
+    #
+    # @param path [String] Path to the collection file
+    # @return [BaseCollection] A new instance
+    # @raise [ArgumentError] if path is nil or empty
+    # @raise [Errno::ENOENT] if file does not exist
+    # @raise [RuntimeError] if file format is invalid
+    def self.from_file(path)
+      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)
+
+      File.open(path, "rb") { |io| read(io) }
+    rescue BinData::ValidityError => e
+      raise "Invalid #{collection_format} file: #{e.message}"
+    rescue EOFError => e
+      raise "Invalid #{collection_format} file: unexpected end of file - #{e.message}"
+    end
+
+    # Extract fonts from the collection
+    #
+    # Reads each font from the collection file and returns them as font objects.
+    #
+    # @param io [IO] Open file handle to read fonts from
+    # @return [Array] Array of font objects (TrueTypeFont or OpenTypeFont)
+    def extract_fonts(io)
+      font_class = self.class.font_class
+
+      font_offsets.map do |offset|
+        font_class.from_collection(io, offset)
+      end
+    end
+
+    # Get a single font from the collection
+    #
+    # @param index [Integer] Index of the font (0-based)
+    # @param io [IO] Open file handle
+    # @param mode [Symbol] Loading mode (:metadata or :full, default: :full)
+    # @return [TrueTypeFont, OpenTypeFont, nil] Font object or nil if index out of range
+    def font(index, io, mode: LoadingModes::FULL)
+      return nil if index >= num_fonts
+
+      font_class = self.class.font_class
+      font_class.from_collection(io, font_offsets[index], mode: mode)
+    end
+
+    # Get font count
+    #
+    # @return [Integer] Number of fonts in collection
+    def font_count
+      num_fonts
+    end
+
+    # Validate format correctness
+    #
+    # @return [Boolean] true if the format is valid, false otherwise
+    def valid?
+      tag == Constants::TTC_TAG && num_fonts.positive? && font_offsets.length == num_fonts
+    rescue StandardError
+      false
+    end
+
+    # Get the collection version as a single integer
+    #
+    # @return [Integer] Version number (e.g., 0x00010000 for version 1.0)
+    def version
+      (major_version << 16) | minor_version
+    end
+
+    # Get the collection version as a string
+    #
+    # @return [String] Version string (e.g., "1.0")
+    def version_string
+      "#{major_version}.#{minor_version}"
+    end
+
+    # List all fonts in the collection with basic metadata
+    #
+    # Returns a CollectionListInfo model containing summaries of all fonts.
+    # This is the API method used by the `ls` command for collections.
+    #
+    # @param io [IO] Open file handle to read fonts from
+    # @return [CollectionListInfo] List of fonts with metadata
+    #
+    # @example List fonts in collection
+    #   File.open("fonts.ttc", "rb") do |io|
+    #     collection = TrueTypeCollection.read(io)
+    #     list = collection.list_fonts(io)
+    #     list.fonts.each { |f| puts "#{f.index}: #{f.family_name}" }
+    #   end
+    def list_fonts(io)
+      require_relative "models/collection_list_info"
+      require_relative "models/collection_font_summary"
+      require_relative "tables/name"
+
+      font_class = self.class.font_class
+
+      fonts = font_offsets.map.with_index do |offset, index|
+        font = font_class.from_collection(io, offset)
+
+        # Extract basic font info
+        name_table = font.table("name")
+        post_table = font.table("post")
+
+        family_name = name_table&.english_name(Tables::Name::FAMILY) || "Unknown"
+        subfamily_name = name_table&.english_name(Tables::Name::SUBFAMILY) || "Regular"
+        postscript_name = name_table&.english_name(Tables::Name::POSTSCRIPT_NAME) || "Unknown"
+
+        # Determine font format
+        sfnt = font.header.sfnt_version
+        font_format = case sfnt
+                      when 0x00010000, 0x74727565 # 0x74727565 = 'true'
+                        "TrueType"
+                      when 0x4F54544F # 'OTTO'
+                        "OpenType"
+                      else
+                        "Unknown"
+                      end
+
+        num_glyphs = post_table&.glyph_names&.length || 0
+        num_tables = font.table_names.length
+
+        Models::CollectionFontSummary.new(
+          index: index,
+          family_name: family_name,
+          subfamily_name: subfamily_name,
+          postscript_name: postscript_name,
+          font_format: font_format,
+          num_glyphs: num_glyphs,
+          num_tables: num_tables,
+        )
+      end
+
+      Models::CollectionListInfo.new(
+        collection_path: nil, # Will be set by command
+        num_fonts: num_fonts,
+        fonts: fonts,
+      )
+    end
+
+    # Get comprehensive collection metadata
+    #
+    # Returns a CollectionInfo model with header information, offsets,
+    # and table sharing statistics.
+    # This is the API method used by the `info` command for collections.
+    #
+    # @param io [IO] Open file handle to read fonts from
+    # @param path [String] Collection file path (for file size)
+    # @return [CollectionInfo] Collection metadata
+    #
+    # @example Get collection info
+    #   File.open("fonts.ttc", "rb") do |io|
+    #     collection = TrueTypeCollection.read(io)
+    #     info = collection.collection_info(io, "fonts.ttc")
+    #     puts "Version: #{info.version_string}"
+    #   end
+    def collection_info(io, path)
+      require_relative "models/collection_info"
+      require_relative "models/table_sharing_info"
+
+      # Calculate table sharing statistics
+      table_sharing = calculate_table_sharing(io)
+
+      # Get file size
+      file_size = path ? File.size(path) : 0
+
+      Models::CollectionInfo.new(
+        collection_path: path,
+        collection_format: self.class.collection_format,
+        ttc_tag: tag,
+        major_version: major_version,
+        minor_version: minor_version,
+        num_fonts: num_fonts,
+        font_offsets: font_offsets.to_a,
+        file_size_bytes: file_size,
+        table_sharing: table_sharing,
+      )
+    end
+
+    private
+
+    # Calculate table sharing statistics
+    #
+    # Analyzes which tables are shared between fonts and calculates
+    # space savings from deduplication.
+    #
+    # @param io [IO] Open file handle
+    # @return [TableSharingInfo] Sharing statistics
+    def calculate_table_sharing(io)
+      require_relative "models/table_sharing_info"
+
+      font_class = self.class.font_class
+
+      # Extract all fonts
+      fonts = font_offsets.map do |offset|
+        font_class.from_collection(io, offset)
+      end
+
+      # Build table hash map (checksum -> size)
+      table_map = {}
+      total_table_size = 0
+
+      fonts.each do |font|
+        font.tables.each do |entry|
+          key = entry.checksum
+          size = entry.table_length
+          table_map[key] ||= size
+          total_table_size += size
+        end
+      end
+
+      # Count unique vs shared
+      unique_tables = table_map.size
+      total_tables = fonts.sum { |f| f.tables.length }
+      shared_tables = total_tables - unique_tables
+
+      # Calculate space saved
+      unique_size = table_map.values.sum
+      space_saved = total_table_size - unique_size
+
+      # Calculate sharing percentage
+      sharing_pct = total_tables.positive? ? (shared_tables.to_f / total_tables * 100).round(2) : 0.0
+
+      Models::TableSharingInfo.new(
+        shared_tables: shared_tables,
+        unique_tables: unique_tables,
+        sharing_percentage: sharing_pct,
+        space_saved_bytes: space_saved,
+      )
+    end
+  end
+end

data/lib/fontisan/cli.rb

@@ -26,6 +26,9 @@ module Fontisan
                          aliases: "-q"
 
     desc "info PATH", "Display font information"
+    option :brief, type: :boolean, default: false,
+                   desc: "Brief mode - only essential info (5x faster, uses metadata loading)",
+                   aliases: "-b"
     # Extract and display comprehensive font metadata.
     #
     # @param path [String] Path to the font file or collection
@@ -33,7 +36,7 @@ module Fontisan
       command = Commands::InfoCommand.new(path, options)
       info = command.run
       output_result(info) unless options[:quiet]
-    rescue Errno::ENOENT => e
+    rescue Errno::ENOENT
       if options[:verbose]
         raise
       else
@@ -270,7 +273,10 @@ module Fontisan
 
       # Merge coordinates into options
       convert_options = options.to_h.dup
-      convert_options[:instance_coordinates] = instance_coords if instance_coords.any?
+      if instance_coords.any?
+        convert_options[:instance_coordinates] =
+          instance_coords
+      end
 
       command = Commands::ConvertCommand.new(font_file, convert_options)
       command.run
@@ -348,7 +354,8 @@ module Fontisan
     option :verbose, type: :boolean, default: false,
                      desc: "Show detailed validation information"
     def validate(font_file)
-      command = Commands::ValidateCommand.new(font_file, verbose: options[:verbose])
+      command = Commands::ValidateCommand.new(font_file,
+                                              verbose: options[:verbose])
       exit command.run
     end
 

data/lib/fontisan/collection/builder.rb

@@ -291,7 +291,8 @@ module Fontisan
         otf_count = variable_fonts.count { |f| f.has_table?("CFF2") }
 
         if ttf_count.positive? && otf_count.positive?
-          raise Error, "Cannot mix TrueType and CFF2 variable fonts in collection"
+          raise Error,
+                "Cannot mix TrueType and CFF2 variable fonts in collection"
         end
       end
 

data/lib/fontisan/collection/offset_calculator.rb

@@ -165,6 +165,7 @@ module Fontisan
           end
         end
 
+        # rubocop:disable Style/CombinableLoops
         # First, assign offsets to shared tables
         # Shared tables are stored once and referenced by multiple fonts
         canonical_tables.each do |canonical_id, info|
@@ -182,6 +183,7 @@ module Fontisan
           @offsets[:table_offsets][canonical_id] = current_offset
           current_offset = align_offset(current_offset + info[:size])
         end
+        # rubocop:enable Style/CombinableLoops
       end
 
       # Align offset to TABLE_ALIGNMENT boundary

data/lib/fontisan/commands/base_command.rb

@@ -82,13 +82,16 @@ module Fontisan
           end
         end
 
+        # Brief mode uses metadata loading for 5x faster parsing
+        mode = @options[:brief] ? LoadingModes::METADATA : (@options[:mode] || LoadingModes::FULL)
+
         # ConvertCommand and similar commands need all tables loaded upfront
         # Use mode and lazy from options, or sensible defaults
         FontLoader.load(
           @font_path,
           font_index: @options[:font_index] || 0,
-          mode: @options[:mode] || LoadingModes::FULL,
-          lazy: @options.key?(:lazy) ? @options[:lazy] : false
+          mode: mode,
+          lazy: @options.key?(:lazy) ? @options[:lazy] : false,
         )
       rescue Errno::ENOENT
         # Re-raise file not found as-is

data/lib/fontisan/commands/convert_command.rb

@@ -89,7 +89,10 @@ module Fontisan
         # Add variation options if specified
         pipeline_options[:coordinates] = @coordinates if @coordinates
         pipeline_options[:instance_index] = @instance_index if @instance_index
-        pipeline_options[:preserve_variation] = @preserve_variation unless @preserve_variation.nil?
+        unless @preserve_variation.nil?
+          pipeline_options[:preserve_variation] =
+            @preserve_variation
+        end
 
         # Add hint preservation option
         pipeline_options[:preserve_hints] = @preserve_hints if @preserve_hints
@@ -155,7 +158,8 @@ module Fontisan
         end
         coords
       rescue StandardError => e
-        raise ArgumentError, "Invalid coordinates format '#{coord_string}': #{e.message}"
+        raise ArgumentError,
+              "Invalid coordinates format '#{coord_string}': #{e.message}"
       end
 
       # Validate command options

data/lib/fontisan/commands/info_command.rb

@@ -41,24 +41,105 @@ module Fontisan
 
       # Get collection information
       #
-      # @return [Models::CollectionInfo] Collection metadata
+      # @return [Models::CollectionInfo, Models::CollectionBriefInfo] Collection metadata
       def collection_info
         collection = FontLoader.load_collection(@font_path)
 
         File.open(@font_path, "rb") do |io|
-          collection.collection_info(io, @font_path)
+          if @options[:brief]
+            # Brief mode: load each font and populate brief info
+            brief_info = Models::CollectionBriefInfo.new
+            brief_info.collection_path = @font_path
+            brief_info.collection_type = collection.class.collection_format
+            brief_info.collection_version = collection.version_string
+            brief_info.num_fonts = collection.num_fonts
+            brief_info.fonts = load_collection_fonts(collection, @font_path)
+
+            brief_info
+          else
+            # Full mode: show detailed sharing statistics AND font information
+            full_info = collection.collection_info(io, @font_path)
+
+            # Add font information to full mode
+            full_info.fonts = load_collection_fonts(collection, @font_path)
+
+            full_info
+          end
         end
       end
 
+      # Load font information for all fonts in a collection
+      #
+      # @param collection [TrueTypeCollection, OpenTypeCollection] The collection
+      # @param collection_path [String] Path to the collection file
+      # @return [Array<Models::FontInfo>] Array of font info objects
+      def load_collection_fonts(collection, collection_path)
+        fonts = []
+
+        collection.num_fonts.times do |index|
+          # Load individual font from collection
+          font = FontLoader.load(collection_path, font_index: index, mode: LoadingModes::METADATA)
+
+          # Populate font info
+          info = Models::FontInfo.new
+
+          # Font format and variable status
+          info.font_format = case font
+                             when TrueTypeFont
+                               "truetype"
+                             when OpenTypeFont
+                               "cff"
+                             else
+                               "unknown"
+                             end
+          info.is_variable = font.has_table?(Constants::FVAR_TAG)
+
+          # Collection offset (only populated for fonts in collections)
+          info.collection_offset = collection.font_offsets[index]
+
+          # Essential names
+          if font.has_table?(Constants::NAME_TAG)
+            name_table = font.table(Constants::NAME_TAG)
+            info.family_name = name_table.english_name(Tables::Name::FAMILY)
+            info.subfamily_name = name_table.english_name(Tables::Name::SUBFAMILY)
+            info.full_name = name_table.english_name(Tables::Name::FULL_NAME)
+            info.postscript_name = name_table.english_name(Tables::Name::POSTSCRIPT_NAME)
+            info.version = name_table.english_name(Tables::Name::VERSION)
+          end
+
+          # Essential metrics
+          if font.has_table?(Constants::HEAD_TAG)
+            head = font.table(Constants::HEAD_TAG)
+            info.font_revision = head.font_revision
+            info.units_per_em = head.units_per_em
+          end
+
+          # Vendor ID
+          if font.has_table?(Constants::OS2_TAG)
+            os2_table = font.table(Constants::OS2_TAG)
+            info.vendor_id = os2_table.vendor_id
+          end
+
+          fonts << info
+        end
+
+        fonts
+      end
+
       # Get individual font information
       #
       # @return [Models::FontInfo] Font metadata
       def font_info
         info = Models::FontInfo.new
         populate_font_format(info)
-        populate_from_name_table(info) if font.has_table?(Constants::NAME_TAG)
-        populate_from_os2_table(info) if font.has_table?(Constants::OS2_TAG)
-        populate_from_head_table(info) if font.has_table?(Constants::HEAD_TAG)
+
+        # In brief mode, only populate essential fields for fast identification
+        if @options[:brief]
+          populate_brief_fields(info)
+        else
+          populate_full_fields(info)
+        end
+
         info
       end
 
@@ -80,6 +161,49 @@ module Fontisan
         info.is_variable = font.has_table?(Constants::FVAR_TAG)
       end
 
+      # Populate essential fields for brief mode (metadata tables only).
+      #
+      # Brief mode provides fast font identification by loading only 13 essential
+      # attributes from metadata tables (name, head, OS/2). This is 5x faster than
+      # full mode and optimized for font indexing systems.
+      #
+      # @param info [Models::FontInfo] FontInfo instance to populate
+      def populate_brief_fields(info)
+        # Essential names from name table
+        if font.has_table?(Constants::NAME_TAG)
+          name_table = font.table(Constants::NAME_TAG)
+          info.family_name = name_table.english_name(Tables::Name::FAMILY)
+          info.subfamily_name = name_table.english_name(Tables::Name::SUBFAMILY)
+          info.full_name = name_table.english_name(Tables::Name::FULL_NAME)
+          info.postscript_name = name_table.english_name(Tables::Name::POSTSCRIPT_NAME)
+          info.version = name_table.english_name(Tables::Name::VERSION)
+        end
+
+        # Essential metrics from head table
+        if font.has_table?(Constants::HEAD_TAG)
+          head = font.table(Constants::HEAD_TAG)
+          info.font_revision = head.font_revision
+          info.units_per_em = head.units_per_em
+        end
+
+        # Vendor ID from OS/2 table
+        if font.has_table?(Constants::OS2_TAG)
+          os2_table = font.table(Constants::OS2_TAG)
+          info.vendor_id = os2_table.vendor_id
+        end
+      end
+
+      # Populate all fields for full mode.
+      #
+      # Full mode extracts comprehensive metadata from all available tables.
+      #
+      # @param info [Models::FontInfo] FontInfo instance to populate
+      def populate_full_fields(info)
+        populate_from_name_table(info) if font.has_table?(Constants::NAME_TAG)
+        populate_from_os2_table(info) if font.has_table?(Constants::OS2_TAG)
+        populate_from_head_table(info) if font.has_table?(Constants::HEAD_TAG)
+      end
+
       # Populate FontInfo from the name table.
       #
       # @param info [Models::FontInfo] FontInfo instance to populate

data/lib/fontisan/commands/instance_command.rb

@@ -67,11 +67,11 @@ module Fontisan
 
         puts "Static font instance written to: #{output_path}"
       rescue VariationError => e
-        $stderr.puts "Variation Error: #{e.detailed_message}"
+        warn "Variation Error: #{e.detailed_message}"
         exit 1
       rescue StandardError => e
-        $stderr.puts "Error: #{e.message}"
-        $stderr.puts e.backtrace.first(5).join("\n") if options[:verbose]
+        warn "Error: #{e.message}"
+        warn e.backtrace.first(5).join("\n") if options[:verbose]
         exit 1
       end
 
@@ -87,9 +87,9 @@ module Fontisan
         errors = validator.validate
 
         if errors.any?
-          $stderr.puts "Validation errors found:"
+          warn "Validation errors found:"
           errors.each do |error|
-            $stderr.puts "  - #{error}"
+            warn "  - #{error}"
           end
           exit 1
         end
@@ -102,7 +102,7 @@ module Fontisan
       # @param font [Object] Font object
       # @param input_path [String] Input file path
       # @param options [Hash] Command options
-      def preview_instance(font, input_path, options)
+      def preview_instance(_font, input_path, options)
         coords = extract_coordinates(options)
 
         if coords.empty?
@@ -117,7 +117,8 @@ module Fontisan
           puts "  #{axis}: #{value}"
         end
         puts
-        puts "Output would be written to: #{determine_output_path(input_path, options)}"
+        puts "Output would be written to: #{determine_output_path(input_path,
+                                                                  options)}"
         puts "Output format: #{options[:to] || 'same as input'}"
         puts
         puts "Use without --dry-run to actually generate the instance."

data/lib/fontisan/commands/validate_command.rb

@@ -84,7 +84,10 @@ quiet: false)
           errors.each do |error|
             puts "  ERROR: #{error}" if @verbose && !@quiet
             # Add to report if report supports adding errors
-            report.errors << { message: error, category: "variable_font" } if report.respond_to?(:errors)
+            if report.respond_to?(:errors)
+              report.errors << { message: error,
+                                 category: "variable_font" }
+            end
           end
         elsif @verbose && !@quiet
           puts "\n✓ Variable font structure valid"

data/lib/fontisan/constants.rb

@@ -117,30 +117,30 @@ module Fontisan
     # These strings are frozen and reused to reduce memory allocations
     # when parsing fonts with common subfamily names.
     STRING_POOL = {
-      "Regular" => "Regular".freeze,
-      "Bold" => "Bold".freeze,
-      "Italic" => "Italic".freeze,
-      "Bold Italic" => "Bold Italic".freeze,
-      "BoldItalic" => "BoldItalic".freeze,
-      "Light" => "Light".freeze,
-      "Medium" => "Medium".freeze,
-      "Semibold" => "Semibold".freeze,
-      "SemiBold" => "SemiBold".freeze,
-      "Black" => "Black".freeze,
-      "Thin" => "Thin".freeze,
-      "ExtraLight" => "ExtraLight".freeze,
-      "Extra Light" => "Extra Light".freeze,
-      "ExtraBold" => "ExtraBold".freeze,
-      "Extra Bold" => "Extra Bold".freeze,
-      "Heavy" => "Heavy".freeze,
-      "Book" => "Book".freeze,
-      "Roman" => "Roman".freeze,
-      "Normal" => "Normal".freeze,
-      "Oblique" => "Oblique".freeze,
-      "Light Italic" => "Light Italic".freeze,
-      "Medium Italic" => "Medium Italic".freeze,
-      "Semibold Italic" => "Semibold Italic".freeze,
-      "Bold Oblique" => "Bold Oblique".freeze,
+      "Regular" => "Regular",
+      "Bold" => "Bold",
+      "Italic" => "Italic",
+      "Bold Italic" => "Bold Italic",
+      "BoldItalic" => "BoldItalic",
+      "Light" => "Light",
+      "Medium" => "Medium",
+      "Semibold" => "Semibold",
+      "SemiBold" => "SemiBold",
+      "Black" => "Black",
+      "Thin" => "Thin",
+      "ExtraLight" => "ExtraLight",
+      "Extra Light" => "Extra Light",
+      "ExtraBold" => "ExtraBold",
+      "Extra Bold" => "Extra Bold",
+      "Heavy" => "Heavy",
+      "Book" => "Book",
+      "Roman" => "Roman",
+      "Normal" => "Normal",
+      "Oblique" => "Oblique",
+      "Light Italic" => "Light Italic",
+      "Medium Italic" => "Medium Italic",
+      "Semibold Italic" => "Semibold Italic",
+      "Bold Oblique" => "Bold Oblique",
     }.freeze
 
     # Intern a string using the string pool