fontisan 0.1.0 → 0.2.0

data/Rakefile

@@ -11,6 +11,20 @@ RuboCop::RakeTask.new
 namespace :fixtures do
   fixtures_dir = "spec/fixtures/fonts"
 
+  # Helper method to download a single file
+  def download_single_file(name, url, target_path)
+    require "open-uri"
+
+    puts "[fixtures:download] Downloading #{name}..."
+    FileUtils.mkdir_p(File.dirname(target_path))
+
+    URI.open(url) do |remote|
+      File.binwrite(target_path, remote.read)
+    end
+
+    puts "[fixtures:download] #{name} downloaded successfully"
+  end
+
   # Helper method to download and extract a font archive
   def download_font(name, url, target_dir)
     require "open-uri"
@@ -44,6 +58,12 @@ namespace :fixtures do
   # Font configurations with target directories and marker files
   # All fonts are downloaded via Rake
   fonts = {
+    "NotoSans" => {
+      url: "https://github.com/notofonts/notofonts.github.io/raw/refs/heads/main/fonts/NotoSans/full/ttf/NotoSans-Regular.ttf",
+      target_dir: fixtures_dir.to_s,
+      marker: "#{fixtures_dir}/NotoSans-Regular.ttf",
+      single_file: true,
+    },
     "Libertinus" => {
       url: "https://github.com/alerque/libertinus/releases/download/v7.051/Libertinus-7.051.zip",
       target_dir: "#{fixtures_dir}/libertinus",
@@ -69,7 +89,11 @@ namespace :fixtures do
   # Create file tasks for each font
   fonts.each do |name, config|
     file config[:marker] do
-      download_font(name, config[:url], config[:target_dir])
+      if config[:single_file]
+        download_single_file(name, config[:url], config[:marker])
+      else
+        download_font(name, config[:url], config[:target_dir])
+      end
     end
   end
 
@@ -78,7 +102,8 @@ namespace :fixtures do
 
   desc "Clean downloaded fixtures"
   task :clean do
-    %w[libertinus MonaSans NotoSerifCJK NotoSerifCJK-VF].each do |dir|
+    %w[libertinus MonaSans NotoSerifCJK NotoSerifCJK-VF
+       NotoSans-Regular.ttf].each do |dir|
       path = File.join(fixtures_dir, dir)
       if File.exist?(path)
         FileUtils.rm_rf(path)

data/benchmark/variation_quick_bench.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'benchmark'
+require 'fontisan'
+
+# Load variable font
+FONT_PATH = 'spec/fixtures/SourceSans3VF-Roman.otf'
+
+unless File.exist?(FONT_PATH)
+  puts "Error: Test font not found at #{FONT_PATH}"
+  exit 1
+end
+
+font = Fontisan::FontLoader.load(FONT_PATH)
+
+puts "=== Variable Font Parallel Performance ==="
+puts "Font: #{FONT_PATH}"
+puts
+
+# Test coordinates
+coords = 4.times.map { |i| { "wght" => 300 + i * 200 } }
+puts "Generating #{coords.size} instances"
+puts
+
+# Sequential (1 thread)
+seq_gen = Fontisan::Variation::ParallelGenerator.new(font, threads: 1)
+seq_time = Benchmark.realtime do
+  seq_gen.generate_batch(coords)
+end
+
+# Parallel (4 threads)
+par_gen = Fontisan::Variation::ParallelGenerator.new(font, threads: 4)
+par_time = Benchmark.realtime do
+  par_gen.generate_batch(coords)
+end
+
+puts "Sequential (1 thread): #{format('%.3f', seq_time)}s"
+puts "Parallel (4 threads):  #{format('%.3f', par_time)}s"
+puts "Speedup: #{format('%.2f', seq_time / par_time)}x"
+puts
+
+# Cache stats
+cache = Fontisan::Variation::ThreadSafeCache.new
+5.times { cache.fetch("test_#{rand(100)}") { rand } }
+
+puts "Cache Statistics:"
+puts cache.statistics.inspect

data/docs/EXTRACT_TTC_MIGRATION.md

@@ -0,0 +1,549 @@
+# Migration Guide: extract_ttc → fontisan
+
+## Overview
+
+**fontisan now fully supersedes extract_ttc** with superior functionality and a better user experience. All extract_ttc features are available in fontisan, plus many more.
+
+## Quick Command Translation
+
+| extract_ttc Command | fontisan Equivalent | Notes |
+|---------------------|---------------------|-------|
+| `extract_ttc ls file.ttc` | `fontisan ls file.ttc` | ✅ Identical output, better formatting |
+| `extract_ttc info file.ttc` | `fontisan info file.ttc` | ✅ Plus table sharing statistics |
+| `extract_ttc extract file.ttc` | `fontisan unpack file.ttc --output-dir .` | ✅ More powerful with format conversion |
+
+## Feature Comparison
+
+| Feature | extract_ttc | fontisan | Advantage |
+|---------|-------------|----------|-----------|
+| **List fonts in TTC** | ✓ | ✓ | Equal |
+| **Show TTC metadata** | ✓ | ✓ | Equal |
+| **Extract TTC fonts** | ✓ | ✓ | Equal |
+| **Table sharing stats** | ✗ | ✓ | 🎯 fontisan |
+| **Auto-detection** | ✗ | ✓ | 🎯 fontisan |
+| **Works on TTF/OTF** | ✗ | ✓ | 🎯 fontisan |
+| **Format conversion** | ✗ | ✓ | 🎯 fontisan |
+| **Output formats** | Text only | Text, YAML, JSON | 🎯 fontisan |
+| **Font analysis** | ✗ | ✓ (17 commands) | 🎯 fontisan |
+| **Variable fonts** | ✗ | ✓ | 🎯 fontisan |
+| **Font subsetting** | ✗ | ✓ | 🎯 fontisan |
+| **Font validation** | ✗ | ✓ | 🎯 fontisan |
+| **Create collections** | ✗ | ✓ | 🎯 fontisan |
+
+## Migration Examples
+
+### Listing Fonts
+
+**extract_ttc:**
+```bash
+extract_ttc ls fonts.ttc
+```
+
+**fontisan:**
+```bash
+fontisan ls fonts.ttc
+```
+
+Output is cleaner and shows more info:
+```
+Collection: fonts.ttc
+Fonts: 2
+
+0. Helvetica Regular
+   PostScript: Helvetica-Regular
+   Format: TrueType
+   Glyphs: 268, Tables: 14
+
+1. Helvetica Bold
+   PostScript: Helvetica-Bold
+   Format: TrueType
+   Glyphs: 268, Tables: 14
+```
+
+### Collection Information
+
+**extract_ttc:**
+```bash
+extract_ttc info fonts.ttc
+```
+
+**fontisan:**
+```bash
+fontisan info fonts.ttc
+```
+
+fontisan shows MORE information:
+```
+=== Collection Information ===
+File: fonts.ttc
+Format: TTC
+Size: 2.55 KB
+
+=== Header ===
+Tag: ttcf
+Version: 1.0
+Number of fonts: 2
+
+=== Font Offsets ===
+  0. Offset:       20
+  1. Offset:      272
+
+=== Table Sharing ===      ← NEW!
+Shared tables: 17          ← NEW!
+Unique tables: 13          ← NEW!
+Sharing: 56.67%           ← NEW!
+Space saved: 2.02 KB      ← NEW!
+```
+
+### Extracting Fonts
+
+**extract_ttc:**
+```bash
+extract_ttc extract fonts.ttc -o output/
+```
+
+**fontisan:**
+```bash
+fontisan unpack fonts.ttc --output-dir output/
+```
+
+fontisan can also convert during extraction:
+```bash
+# Extract as WOFF2 for web use
+fontisan unpack fonts.ttc --output-dir web/ --format woff2
+
+# Extract specific font only
+fontisan unpack fonts.ttc --output-dir . --font-index 0
+```
+
+## Why Switch to fontisan?
+
+### 1. Universal Commands
+
+fontisan commands work on **all** font formats:
+```bash
+# Works on collections
+fontisan ls fonts.ttc
+fontisan info fonts.ttc
+
+# Also works on individual fonts
+fontisan ls font.ttf
+fontisan info font.otf
+```
+
+### 2. Comprehensive Font Analysis
+
+Beyond extract_ttc, fontisan provides:
+
+```bash
+# Analyze font features
+fontisan features font.ttf --script latn
+
+# Check variable font axes
+fontisan variable VariableFont.ttf
+
+# Validate font integrity
+fontisan validate font.ttf
+
+# Subset to specific characters
+fontisan subset font.ttf --text "Hello" --output hello.ttf
+
+# Convert formats
+fontisan convert font.ttf --to woff2 --output font.woff2
+
+# Create collections
+fontisan pack Regular.ttf Bold.ttf --output Family.ttc
+```
+
+### 3. Modern Output Formats
+
+```bash
+# Human-readable text (default)
+fontisan info fonts.ttc
+
+# Machine-readable YAML
+fontisan info fonts.ttc --format yaml
+
+# Machine-readable JSON
+fontisan info fonts.ttc --format json
+```
+
+### 4. Better Error Messages
+
+fontisan provides clear, actionable error messages:
+```
+Error: Font index 5 out of range (collection has 2 fonts)
+```
+
+vs extract_ttc generic Ruby errors.
+
+## Installation
+
+### Remove extract_ttc (optional)
+
+```bash
+gem uninstall extract_ttc
+```
+
+### Install fontisan
+
+```bash
+gem install fontisan
+```
+
+Or add to Gemfile:
+```ruby
+gem 'fontisan'
+```
+
+## API Usage
+
+### extract_ttc API
+
+```ruby
+require 'extract_ttc'
+
+# List fonts
+output_files = ExtractTtc.extract("fonts.ttc")
+```
+
+### fontisan API (More Powerful)
+
+```ruby
+require 'fontisan'
+
+# List fonts in collection
+collection = Fontisan::FontLoader.load_collection("fonts.ttc")
+File.open("fonts.ttc", "rb") do |io|
+  list = collection.list_fonts(io)
+  list.fonts.each { |f| puts "#{f.index}: #{f.family_name}" }
+end
+
+# Get collection metadata
+File.open("fonts.ttc", "rb") do |io|
+  info = collection.collection_info(io, "fonts.ttc")
+  puts "Fonts: #{info.num_fonts}"
+  puts "Sharing: #{info.table_sharing.sharing_percentage}%"
+end
+
+# Extract fonts with more control
+File.open("fonts.ttc", "rb") do |io|
+  fonts = collection.extract_fonts(io)
+  fonts.each_with_index do |font, i|
+    font.to_file("output/font_#{i}.ttf")
+  end
+end
+```
+
+## Backward Compatibility
+
+fontisan maintains 100% backward compatibility:
+- All existing `fontisan` commands continue to work
+- No breaking changes to existing functionality
+- New commands add features without removing anything
+
+#=========================================================================
+
+= ExtractTTC to Fontisan Migration Guide
+
+This guide helps users migrate from https://github.com/fontist/extract_ttc[ExtractTTC] to Fontisan.
+
+Fontisan provides complete compatibility with all ExtractTTC functionality while adding comprehensive font analysis, subsetting, validation, and format conversion capabilities.
+
+== Command Mapping Reference
+
+[cols="2,2,3"]
+|===
+|ExtractTTC Command |Fontisan Equivalent |Description
+
+|`extract_ttc --list FONT.ttc`
+|`fontisan ls FONT.ttc`
+|List fonts in collection with index, family, and style
+
+|`extract_ttc --info FONT.ttc`
+|`fontisan info FONT.ttc`
+|Show detailed font information for collection
+
+|`extract_ttc --unpack FONT.ttc OUTPUT_DIR`
+|`fontisan unpack FONT.ttc OUTPUT_DIR`
+|Extract all fonts from collection to directory
+
+|`extract_ttc --font-index INDEX FONT.ttc OUTPUT.ttf`
+|`fontisan unpack FONT.ttc --font-index INDEX OUTPUT.ttf`
+|Extract specific font by index
+
+|`extract_ttc --validate FONT.ttc`
+|`fontisan validate FONT.ttc`
+|Validate font/collection structure and checksums
+|===
+
+== Enhanced Collection Management
+
+Fontisan provides additional collection features beyond ExtractTTC:
+
+=== List Collection Contents
+
+[source,shell]
+----
+# List all fonts in a TTC with detailed info
+$ fontisan ls spec/fixtures/fonts/NotoSerifCJK/NotoSerifCJK.ttc
+
+Font 0: Noto Serif CJK JP
+  Family: Noto Serif CJK JP
+  Subfamily: Regular
+  PostScript: NotoSerifCJKJP-Regular
+
+Font 1: Noto Serif CJK KR
+  Family: Noto Serif CJK KR
+  Subfamily: Regular
+  PostScript: NotoSerifCJKKR-Regular
+
+Font 2: Noto Serif CJK SC
+  Family: Noto Serif CJK SC
+  Subfamily: Regular
+  PostScript: NotoSerifCJKSC-Regular
+
+Font 3: Noto Serif CJK TC
+  Family: Noto Serif CJK TC
+  Subfamily: Regular
+  PostScript: NotoSerifCJKTC-Regular
+----
+
+=== Extract with Validation
+
+[source,shell]
+----
+# Extract and validate simultaneously
+$ fontisan unpack spec/fixtures/fonts/NotoSerifCJK/NotoSerifCJK.ttc extracted_fonts/ --validate
+
+Extracting font 0: Noto Serif CJK JP → extracted_fonts/NotoSerifCJKJP-Regular.ttf
+Extracting font 1: Noto Serif CJK KR → extracted_fonts/NotoSerifCJKKR-Regular.ttf
+Extracting font 2: Noto Serif CJK SC → extracted_fonts/NotoSerifCJKSC-Regular.ttf
+Extracting font 3: Noto Serif CJK TC → extracted_fonts/NotoSerifCJKTC-Regular.ttf
+
+Validation: All fonts extracted successfully
+----
+
+=== Get Collection Information
+
+[source,shell]
+----
+# Detailed collection analysis
+$ fontisan info spec/fixtures/fonts/NotoSerifCJK/NotoSerifCJK.ttc --format yaml
+
+---
+collection_type: ttc
+font_count: 4
+fonts:
+- index: 0
+  family_name: Noto Serif CJK JP
+  subfamily_name: Regular
+  postscript_name: NotoSerifCJKJP-Regular
+  font_format: opentype
+- index: 1
+  family_name: Noto Serif CJK KR
+  subfamily_name: Regular
+  postscript_name: NotoSerifCJKKR-Regular
+  font_format: opentype
+- index: 2
+  family_name: Noto Serif CJK SC
+  subfamily_name: Regular
+  postscript_name: NotoSerifCJKSC-Regular
+  font_format: opentype
+- index: 3
+  family_name: Noto Serif CJK TC
+  subfamily_name: Regular
+  postscript_name: NotoSerifCJKTC-Regular
+  font_format: opentype
+----
+
+== Advanced Features Beyond ExtractTTC
+
+Fontisan provides capabilities that ExtractTTC never had:
+
+=== Collection Creation
+
+Create new TTC/OTC files from individual fonts with automatic table sharing optimization:
+
+[source,shell]
+----
+# Pack fonts into TTC with table sharing optimization
+$ fontisan pack font1.ttf font2.ttf font3.ttf --output family.ttc --analyze
+
+Collection Analysis:
+Total fonts: 3
+Shared tables: 12
+Potential space savings: 45.2 KB
+Table sharing: 68.5%
+
+Collection created successfully:
+  Output: family.ttc
+  Format: TTC
+  Fonts: 3
+  Size: 245.8 KB
+  Space saved: 45.2 KB
+  Sharing: 68.5%
+----
+
+=== Format Conversion and Subsetting
+
+Convert between font formats and create optimized subsets:
+
+[source,shell]
+----
+# Convert TTF to WOFF2 for web usage
+$ fontisan convert font.ttf --to woff2 --output font.woff2
+
+# Create PDF-optimized subset
+$ fontisan subset font.ttf --text "Hello World" --output subset.ttf --profile pdf
+----
+
+=== Font Analysis and Inspection
+
+Comprehensive font analysis capabilities:
+
+[source,shell]
+----
+# Extract OpenType tables with details
+$ fontisan tables font.ttf --format yaml
+
+# Display variable font information
+$ fontisan variable font.ttf
+
+# Show supported scripts and features
+$ fontisan scripts font.ttf
+$ fontisan features font.ttf --script latn
+
+# Dump raw table data for analysis
+$ fontisan dump-table font.ttf name > name_table.bin
+----
+
+=== Font Validation
+
+Multiple validation levels with detailed reporting:
+
+[source,shell]
+----
+# Standard validation (allows warnings)
+$ fontisan validate font.ttf
+
+# Strict validation (no warnings allowed)
+$ fontisan validate font.ttf --level strict
+
+# Detailed validation report
+$ fontisan validate font.ttf --format yaml
+----
+
+== Migration Examples
+
+=== Basic Collection Operations
+
+[source,shell]
+# ExtractTTC style operations
+extract_ttc --list collection.ttc
+fontisan ls collection.ttc
+
+extract_ttc --info collection.ttc
+fontisan info collection.ttc
+
+extract_ttc --unpack collection.ttc output_dir/
+fontisan unpack collection.ttc output_dir/
+
+extract_ttc --font-index 0 collection.ttc font0.ttf
+fontisan unpack collection.ttc --font-index 0 font0.ttf
+----
+
+=== Enhanced Operations (Fontisan Only)
+
+[source,shell]
+# Create collections (not possible with ExtractTTC)
+fontisan pack font1.ttf font2.ttf --output new_collection.ttc
+
+# Convert formats
+fontisan convert font.ttf --to woff2 --output font.woff2
+
+# Create subsets
+fontisan subset font.ttf --unicode "U+0041-U+005A" --output latin.ttf
+
+# Validate fonts
+fontisan validate font.ttf --level strict
+
+# Analyze fonts
+fontisan scripts font.ttf
+fontisan features font.ttf --script latn
+fontisan variable font.ttf
+----
+
+== Configuration and Options
+
+Fontisan provides extensive configuration options:
+
+=== Global Options
+All commands support these options:
+
+* `--format FORMAT`: Output format (`text`, `json`, `yaml`)
+* `--font-index INDEX`: Font index for TTC files (default: 0)
+* `--verbose`: Enable verbose output
+* `--quiet`: Suppress non-error output
+
+=== Collection-Specific Options
+
+* `--analyze`: Show space analysis for pack operations
+* `--optimize`: Enable table sharing optimization (default: true)
+* `--format {ttc|otc}`: Collection format for pack operations
+
+=== Conversion Options
+
+* `--to FORMAT`: Target format for conversion
+* `--quality LEVEL`: Compression quality (0-11)
+* `--profile PROFILE`: Subsetting profile (`pdf`, `web`, `minimal`)
+
+== Error Handling
+
+Fontisan provides improved error handling compared to ExtractTTC:
+
+[source,shell]
+----
+# Clear error messages
+$ fontisan convert font.ttf --to unsupported
+Error: Unsupported conversion from ttf to unsupported
+Available targets: ttf, otf, woff2, svg
+
+# Helpful validation errors
+$ fontisan validate corrupted.ttf
+Validation failed: Invalid checksum in head table
+----
+
+== Performance
+
+Fontisan is optimized for performance:
+
+* **Collection Operations**: Sub-second for typical collections
+* **Format Conversion**: <1 second for most conversions
+* **Font Analysis**: <100ms for table inspection
+* **Memory Efficient**: Streaming processing for large fonts
+
+== Backward Compatibility
+
+Fontisan maintains full backward compatibility:
+
+* All ExtractTTC commands work identically
+* Same exit codes and error handling
+* Compatible with existing scripts and workflows
+* Enhanced with additional features
+
+== Getting Help
+
+[source,shell]
+----
+# General help
+$ fontisan --help
+
+# Command-specific help
+$ fontisan pack --help
+$ fontisan convert --help
+$ fontisan subset --help
+
+# Version information
+$ fontisan version
+----

data/fontisan.gemspec

@@ -38,7 +38,10 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_dependency "base64"
   spec.add_dependency "bindata", "~> 2.5"
+  spec.add_dependency "brotli", "~> 0.5"
   spec.add_dependency "lutaml-model", "~> 0.7"
-  spec.add_dependency "thor", "~> 1.4"
+  spec.add_dependency "nokogiri", "~> 1.16"
+  spec.add_dependency "thor", "~> 1.3"
 end

data/lib/fontisan/binary/base_record.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "bindata"
+require "stringio"
 
 module Fontisan
   module Binary
@@ -25,7 +26,27 @@ module Fontisan
       def self.read(io)
         return new if io.nil? || (io.respond_to?(:empty?) && io.empty?)
 
-        super
+        # Store the original data for later parsing
+        # Convert IO to string if needed
+        if io.is_a?(String)
+          data = io
+          instance = super(StringIO.new(data))
+        else
+          # For IO objects, read to string first
+          data = io.read
+          io.rewind if io.respond_to?(:rewind)
+          instance = super(io)
+        end
+
+        instance.instance_variable_set(:@raw_data, data)
+        instance
+      end
+
+      # Get the raw binary data that was read
+      #
+      # @return [String] Raw binary data
+      def raw_data
+        @raw_data || to_binary_s
       end
 
       # Check if the record is valid