fontisan 0.1.0 → 0.2.0

data/lib/fontisan/cli.rb

@@ -37,6 +37,27 @@ module Fontisan
       handle_error(e)
     end
 
+    desc "ls FILE", "List contents (fonts in collection or font summary)"
+    # List contents of font files with auto-detection.
+    #
+    # For collections (TTC/OTC): Lists all fonts in the collection
+    # For individual fonts (TTF/OTF): Shows quick font summary
+    #
+    # @param file [String] Path to the font or collection file
+    #
+    # @example List fonts in collection
+    #   fontisan ls fonts.ttc
+    #
+    # @example Show font summary
+    #   fontisan ls font.ttf
+    def ls(file)
+      command = Commands::LsCommand.new(file, options)
+      result = command.run
+      output_result(result)
+    rescue Errno::ENOENT, Error => e
+      handle_error(e)
+    end
+
     desc "tables FONT_FILE", "List OpenType tables"
     # List all OpenType tables in the font file.
     #
@@ -125,6 +146,151 @@ module Fontisan
       handle_error(e)
     end
 
+    desc "subset FONT_FILE", "Subset a font to specific glyphs"
+    option :text, type: :string,
+                  desc: "Text to subset (e.g., 'Hello World')",
+                  aliases: "-t"
+    option :glyphs, type: :string,
+                    desc: "Comma-separated glyph IDs (e.g., '0,1,65,66,67')",
+                    aliases: "-g"
+    option :unicode, type: :string,
+                     desc: "Comma-separated Unicode codepoints (e.g., 'U+0041,U+0042' or '0x41,0x42')",
+                     aliases: "-u"
+    option :output, type: :string, required: true,
+                    desc: "Output file path",
+                    aliases: "-o"
+    option :profile, type: :string, default: "pdf",
+                     desc: "Subsetting profile (pdf, web, minimal)",
+                     aliases: "-p"
+    option :retain_gids, type: :boolean, default: false,
+                         desc: "Retain original glyph IDs (leave gaps)"
+    option :drop_hints, type: :boolean, default: false,
+                        desc: "Drop hinting instructions"
+    option :drop_names, type: :boolean, default: false,
+                        desc: "Drop glyph names from post table"
+    option :unicode_ranges, type: :boolean, default: true,
+                            desc: "Prune OS/2 Unicode ranges"
+    # Subset a font to specific glyphs.
+    #
+    # You must specify one of --text, --glyphs, or --unicode to define
+    # which glyphs to include in the subset.
+    #
+    # @param font_file [String] Path to the font file
+    def subset(font_file)
+      command = Commands::SubsetCommand.new(font_file, options)
+      result = command.run
+
+      unless options[:quiet]
+        puts "Subset font created:"
+        puts "  Input: #{result[:input]}"
+        puts "  Output: #{result[:output]}"
+        puts "  Original glyphs: #{result[:original_glyphs]}"
+        puts "  Subset glyphs: #{result[:subset_glyphs]}"
+        puts "  Profile: #{result[:profile]}"
+        puts "  Size: #{format_size(result[:size])}"
+      end
+    rescue Errno::ENOENT, Error => e
+      handle_error(e)
+    end
+
+    desc "convert FONT_FILE", "Convert font to different format"
+    option :to, type: :string, required: true,
+                desc: "Target format (ttf, otf, woff2, svg)",
+                aliases: "-t"
+    option :output, type: :string, required: true,
+                    desc: "Output file path",
+                    aliases: "-o"
+    option :optimize, type: :boolean, default: false,
+                      desc: "Optimize CFF with subroutines (TTF→OTF only)"
+    option :min_pattern_length, type: :numeric, default: 10,
+                                desc: "Minimum pattern length for subroutines"
+    option :max_subroutines, type: :numeric, default: 65_535,
+                             desc: "Maximum number of subroutines"
+    option :optimize_ordering, type: :boolean, default: true,
+                               desc: "Optimize subroutine ordering by frequency"
+    # Convert a font to a different format.
+    #
+    # Supported conversions:
+    # - Same format (ttf→ttf, otf→otf): Copy/optimize
+    # - TTF ↔ OTF: Outline format conversion (foundation)
+    # - Future: WOFF2 compression, SVG export
+    #
+    # Subroutine Optimization (--optimize):
+    # When converting TTF→OTF, you can enable automatic CFF subroutine generation
+    # to reduce file size. This analyzes repeated byte patterns across glyphs and
+    # creates shared subroutines, typically saving 30-50% in CFF table size.
+    #
+    # @param font_file [String] Path to the font file
+    #
+    # @example Convert TTF to OTF
+    #   fontisan convert font.ttf --to otf --output font.otf
+    #
+    # @example Convert with optimization
+    #   fontisan convert font.ttf --to otf --output font.otf --optimize --verbose
+    #
+    # @example Convert with custom optimization parameters
+    #   fontisan convert font.ttf --to otf --output font.otf --optimize \
+    #     --min-pattern-length 15 --max-subroutines 10000
+    #
+    # @example Copy/optimize TTF
+    #   fontisan convert font.ttf --to ttf --output optimized.ttf
+    def convert(font_file)
+      command = Commands::ConvertCommand.new(font_file, options)
+      command.run
+    rescue Errno::ENOENT, Error => e
+      handle_error(e)
+    end
+
+    desc "instance FONT_FILE",
+         "Generate static font instance from variable font"
+    option :output, type: :string,
+                    desc: "Output file path",
+                    aliases: "-o"
+    option :wght, type: :numeric,
+                  desc: "Weight axis value"
+    option :wdth, type: :numeric,
+                  desc: "Width axis value"
+    option :slnt, type: :numeric,
+                  desc: "Slant axis value"
+    option :ital, type: :numeric,
+                  desc: "Italic axis value"
+    option :opsz, type: :numeric,
+                  desc: "Optical size axis value"
+    option :named_instance, type: :string,
+                            desc: "Use named instance (e.g., 'Bold', 'Light')",
+                            aliases: "-n"
+    option :list_instances, type: :boolean, default: false,
+                            desc: "List available named instances",
+                            aliases: "-l"
+    option :to, type: :string,
+                desc: "Convert to format (ttf, otf, woff, woff2, svg)",
+                aliases: "-t"
+    # Generate static font instance from variable font.
+    #
+    # You can specify axis coordinates using --wght, --wdth, etc., or use
+    # a predefined named instance with --named-instance. Use --list-instances
+    # to see available named instances.
+    #
+    # @param font_file [String] Path to the variable font file
+    #
+    # @example Generate bold instance
+    #   fontisan instance variable.ttf --wght=700 --output=bold.ttf
+    #
+    # @example Use named instance
+    #   fontisan instance variable.ttf --named-instance="Bold" --output=bold.ttf
+    #
+    # @example Instance with format conversion
+    #   fontisan instance variable.ttf --wght=700 --to=woff2 --output=bold.woff2
+    #
+    # @example List available instances
+    #   fontisan instance variable.ttf --list-instances
+    def instance(font_file)
+      command = Commands::InstanceCommand.new
+      command.execute(font_file, options)
+    rescue Errno::ENOENT, Error => e
+      handle_error(e)
+    end
+
     desc "dump-table FONT_FILE TABLE_TAG", "Dump raw table data to stdout"
     # Dump raw binary table data to stdout.
     #
@@ -141,12 +307,141 @@ module Fontisan
       handle_error(e)
     end
 
+    desc "validate FONT_FILE", "Validate font file structure and checksums"
+    option :verbose, type: :boolean, default: false,
+                     desc: "Show detailed validation information"
+    def validate(font_file)
+      command = Commands::ValidateCommand.new(font_file, verbose: options[:verbose])
+      exit command.run
+    end
+
+    desc "export FONT_FILE", "Export font to TTX/YAML/JSON format"
+    option :output, type: :string,
+                    desc: "Output file path (default: stdout)",
+                    aliases: "-o"
+    option :format, type: :string, default: "yaml",
+                    desc: "Export format (yaml, json, ttx)",
+                    aliases: "-f"
+    option :tables, type: :array,
+                    desc: "Specific tables to export",
+                    aliases: "-t"
+    option :binary_format, type: :string, default: "hex",
+                           desc: "Binary encoding (hex, base64)",
+                           aliases: "-b"
+
+    def export(font_file)
+      command = Commands::ExportCommand.new(
+        font_file,
+        output: options[:output],
+        format: options[:format].to_sym,
+        tables: options[:tables],
+        binary_format: options[:binary_format].to_sym,
+      )
+      exit command.run
+    end
+
     desc "version", "Display version information"
     # Display the Fontisan version.
     def version
       puts "Fontisan version #{Fontisan::VERSION}"
     end
 
+    desc "unpack FONT_FILE", "Unpack fonts from TTC/OTC collection"
+    option :output_dir, type: :string, required: true,
+                        desc: "Output directory for extracted fonts",
+                        aliases: "-d"
+    option :font_index, type: :numeric,
+                        desc: "Extract specific font by index (default: extract all)",
+                        aliases: "-i"
+    option :format, type: :string,
+                    desc: "Output format (ttf, otf, woff, woff2)",
+                    aliases: "-f"
+    option :prefix, type: :string,
+                    desc: "Filename prefix for extracted fonts",
+                    aliases: "-p"
+    # Extract individual fonts from a TTC (TrueType Collection) or OTC (OpenType Collection) file.
+    #
+    # This command unpacks fonts from collection files, optionally converting them
+    # to different formats during extraction.
+    #
+    # @param font_file [String] Path to the TTC/OTC collection file
+    #
+    # @example Extract all fonts to directory
+    #   fontisan unpack family.ttc --output-dir extracted/
+    #
+    # @example Extract specific font by index
+    #   fontisan unpack family.ttc --output-dir extracted/ --font-index 0
+    #
+    # @example Extract with format conversion
+    #   fontisan unpack family.ttc --output-dir extracted/ --format woff2
+    #
+    # @example Extract with custom prefix
+    #   fontisan unpack family.ttc --output-dir extracted/ --prefix "NotoSans"
+    def unpack(font_file)
+      command = Commands::UnpackCommand.new(font_file, options)
+      result = command.run
+
+      unless options[:quiet]
+        puts "Collection unpacked successfully:"
+        puts "  Input: #{result[:collection]}"
+        puts "  Output directory: #{result[:output_dir]}"
+        puts "  Fonts extracted: #{result[:fonts_extracted]}/#{result[:num_fonts]}"
+        result[:extracted_files].each do |file|
+          size = File.size(file)
+          puts "  - #{File.basename(file)} (#{format_size(size)})"
+        end
+      end
+    rescue Errno::ENOENT, Error => e
+      handle_error(e)
+    end
+
+    desc "pack FONT_FILES...", "Pack multiple fonts into TTC/OTC collection"
+    option :output, type: :string, required: true,
+                    desc: "Output collection file path",
+                    aliases: "-o"
+    option :format, type: :string, default: "ttc",
+                    desc: "Collection format (ttc, otc)",
+                    aliases: "-f"
+    option :optimize, type: :boolean, default: true,
+                      desc: "Enable table sharing optimization",
+                      aliases: "--optimize"
+    option :analyze, type: :boolean, default: false,
+                     desc: "Show analysis report before building",
+                     aliases: "--analyze"
+    # Create a TTC (TrueType Collection) or OTC (OpenType Collection) from multiple font files.
+    #
+    # This command combines multiple fonts into a single collection file with
+    # shared table deduplication to save space. It supports both TTC and OTC formats.
+    #
+    # @param font_files [Array<String>] Paths to input font files (minimum 2 required)
+    #
+    # @example Pack fonts into TTC
+    #   fontisan pack font1.ttf font2.ttf font3.ttf --output family.ttc
+    #
+    # @example Pack into OTC with analysis
+    #   fontisan pack Regular.otf Bold.otf Italic.otf --output family.otc --analyze
+    #
+    # @example Pack without optimization
+    #   fontisan pack font1.ttf font2.ttf --output collection.ttc --no-optimize
+    def pack(*font_files)
+      command = Commands::PackCommand.new(font_files, options)
+      result = command.run
+
+      unless options[:quiet]
+        puts "Collection created successfully:"
+        puts "  Output: #{result[:output]}"
+        puts "  Format: #{result[:format].upcase}"
+        puts "  Fonts: #{result[:num_fonts]}"
+        puts "  Size: #{format_size(result[:output_size])}"
+        if result[:space_savings].positive?
+          puts "  Space saved: #{format_size(result[:space_savings])}"
+          puts "  Sharing: #{result[:sharing_percentage]}%"
+        end
+      end
+    rescue Errno::ENOENT, Error => e
+      handle_error(e)
+    end
+
     private
 
     # Output the result in the requested format.
@@ -174,6 +469,20 @@ module Fontisan
       formatter.format(result)
     end
 
+    # Format file size in human-readable form
+    #
+    # @param size [Integer] Size in bytes
+    # @return [String] Formatted size
+    def format_size(size)
+      if size < 1024
+        "#{size} bytes"
+      elsif size < 1024 * 1024
+        "#{(size / 1024.0).round(2)} KB"
+      else
+        "#{(size / (1024.0 * 1024)).round(2)} MB"
+      end
+    end
+
     # Handle errors based on verbosity settings.
     #
     # @param error [Error, Errno::ENOENT] The error to handle

data/lib/fontisan/collection/builder.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require_relative "table_analyzer"
+require_relative "table_deduplicator"
+require_relative "offset_calculator"
+require_relative "writer"
+require "yaml"
+
+module Fontisan
+  module Collection
+    # CollectionBuilder orchestrates TTC/OTC creation
+    #
+    # Main responsibility: Coordinate the entire collection creation process
+    # including analysis, deduplication, offset calculation, and writing.
+    # Implements builder pattern for flexible configuration.
+    #
+    # @example Create TTC with default options
+    #   builder = CollectionBuilder.new([font1, font2, font3])
+    #   builder.build_to_file("family.ttc")
+    #
+    # @example Create OTC with optimization
+    #   builder = CollectionBuilder.new([font1, font2, font3])
+    #   builder.format = :otc
+    #   builder.optimize = true
+    #   result = builder.build
+    #   puts "Saved #{result[:space_savings]} bytes"
+    class Builder
+      # Source fonts
+      # @return [Array<TrueTypeFont, OpenTypeFont>]
+      attr_reader :fonts
+
+      # Collection format (:ttc or :otc)
+      # @return [Symbol]
+      attr_accessor :format
+
+      # Enable table sharing optimization
+      # @return [Boolean]
+      attr_accessor :optimize
+
+      # Configuration settings
+      # @return [Hash]
+      attr_accessor :config
+
+      # Build result (populated after build)
+      # @return [Hash, nil]
+      attr_reader :result
+
+      # Initialize builder with fonts
+      #
+      # @param fonts [Array<TrueTypeFont, OpenTypeFont>] Fonts to pack
+      # @param options [Hash] Builder options
+      # @option options [Symbol] :format Format type (:ttc or :otc, default: :ttc)
+      # @option options [Boolean] :optimize Enable optimization (default: true)
+      # @option options [Hash] :config Configuration overrides
+      # @raise [ArgumentError] if fonts array is invalid
+      def initialize(fonts, options = {})
+        if fonts.nil? || fonts.empty?
+          raise ArgumentError,
+                "fonts cannot be nil or empty"
+        end
+        raise ArgumentError, "fonts must be an array" unless fonts.is_a?(Array)
+
+        unless fonts.all? do |f|
+          f.respond_to?(:table_data)
+        end
+          raise ArgumentError,
+                "all fonts must respond to table_data"
+        end
+
+        @fonts = fonts
+        @format = options[:format] || :ttc
+        @optimize = options.fetch(:optimize, true)
+        @config = load_config.merge(options[:config] || {})
+        @result = nil
+
+        validate_format!
+      end
+
+      # Build collection and return binary
+      #
+      # Executes the complete collection creation process:
+      # 1. Analyze tables across fonts
+      # 2. Deduplicate identical tables
+      # 3. Calculate file offsets
+      # 4. Write binary structure
+      #
+      # @return [Hash] Build result with:
+      #   - :binary [String] - Complete collection binary
+      #   - :space_savings [Integer] - Bytes saved by sharing
+      #   - :analysis [Hash] - Analysis report
+      #   - :statistics [Hash] - Deduplication statistics
+      def build
+        # Step 1: Analyze tables
+        analyzer = TableAnalyzer.new(@fonts)
+        analysis_report = analyzer.analyze
+
+        # Step 2: Deduplicate tables
+        deduplicator = TableDeduplicator.new(@fonts)
+        sharing_map = deduplicator.build_sharing_map
+        statistics = deduplicator.statistics
+
+        # Step 3: Calculate offsets
+        calculator = OffsetCalculator.new(sharing_map, @fonts)
+        offsets = calculator.calculate
+
+        # Step 4: Write collection
+        writer = Writer.new(@fonts, sharing_map, offsets, format: @format)
+        binary = writer.write_collection
+
+        # Store result
+        @result = {
+          binary: binary,
+          space_savings: analysis_report[:space_savings],
+          analysis: analysis_report,
+          statistics: statistics,
+          format: @format,
+          num_fonts: @fonts.size,
+        }
+
+        @result
+      end
+
+      # Build collection and write to file
+      #
+      # @param path [String] Output file path
+      # @return [Hash] Build result (same as build method)
+      def build_to_file(path)
+        result = build
+        File.binwrite(path, result[:binary])
+        result[:output_path] = path
+        result[:output_size] = result[:binary].bytesize
+        result
+      end
+
+      # Get analysis report
+      #
+      # Runs analysis without building the full collection.
+      # Useful for previewing space savings before committing to build.
+      #
+      # @return [Hash] Analysis report
+      def analyze
+        analyzer = TableAnalyzer.new(@fonts)
+        analyzer.analyze
+      end
+
+      # Get potential space savings without building
+      #
+      # @return [Integer] Bytes that can be saved
+      def potential_savings
+        analyze[:space_savings]
+      end
+
+      # Validate collection can be built
+      #
+      # @return [Boolean] true if valid, raises error otherwise
+      # @raise [Error] if validation fails
+      def validate!
+        # Check minimum fonts
+        raise Error, "Collection requires at least 2 fonts" if @fonts.size < 2
+
+        # Check format compatibility
+        incompatible = check_format_compatibility
+        if incompatible.any?
+          raise Error, "Format mismatch: #{incompatible.join(', ')}"
+        end
+
+        # Check all fonts have required tables
+        @fonts.each_with_index do |font, index|
+          required_tables = %w[head hhea maxp]
+          missing = required_tables.reject { |tag| font.has_table?(tag) }
+          unless missing.empty?
+            raise Error,
+                  "Font #{index} missing required tables: #{missing.join(', ')}"
+          end
+        end
+
+        true
+      end
+
+      private
+
+      # Load configuration from file
+      #
+      # @return [Hash] Configuration hash
+      def load_config
+        config_path = File.join(__dir__, "..", "config",
+                                "collection_settings.yml")
+        if File.exist?(config_path)
+          YAML.load_file(config_path)
+        else
+          default_config
+        end
+      rescue StandardError => e
+        warn "Failed to load config: #{e.message}, using defaults"
+        default_config
+      end
+
+      # Default configuration
+      #
+      # @return [Hash] Default settings
+      def default_config
+        {
+          "table_sharing_strategy" => "conservative",
+          "alignment" => 4,
+          "optimize_table_order" => true,
+          "verify_checksums" => true,
+        }
+      end
+
+      # Validate format is supported
+      #
+      # @return [void]
+      # @raise [ArgumentError] if format is invalid
+      def validate_format!
+        valid_formats = %i[ttc otc]
+        return if valid_formats.include?(@format)
+
+        raise ArgumentError,
+              "Invalid format: #{@format}. Must be one of: #{valid_formats.join(', ')}"
+      end
+
+      # Check if all fonts are compatible with selected format
+      #
+      # @return [Array<String>] Array of incompatibility messages
+      def check_format_compatibility
+        incompatible = []
+
+        if @format == :ttc
+          # TTC requires TrueType fonts (sfnt version 0x00010000 or 'true')
+          @fonts.each_with_index do |font, index|
+            sfnt = font.header.sfnt_version
+            unless [0x00010000, 0x74727565].include?(sfnt) # 0x74727565 = 'true'
+              incompatible << "Font #{index} is not TrueType (sfnt: 0x#{sfnt.to_s(16)})"
+            end
+          end
+        elsif @format == :otc
+          # OTC can contain both TrueType and OpenType/CFF fonts
+          # No strict validation needed, but warn about mixing
+          has_truetype = false
+          has_opentype = false
+
+          @fonts.each do |font|
+            sfnt = font.header.sfnt_version
+            if [0x00010000, 0x74727565].include?(sfnt)
+              has_truetype = true
+            elsif sfnt == 0x4F54544F # 'OTTO'
+              has_opentype = true
+            end
+          end
+
+          if has_truetype && has_opentype
+            warn "Warning: Mixing TrueType and OpenType/CFF fonts in OTC"
+          end
+        end
+
+        incompatible
+      end
+    end
+  end
+end