fontisan 0.1.0

data/Rakefile

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "fileutils"
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+namespace :fixtures do
+  fixtures_dir = "spec/fixtures/fonts"
+
+  # Helper method to download and extract a font archive
+  def download_font(name, url, target_dir)
+    require "open-uri"
+    require "zip"
+
+    zip_file = "#{target_dir}/#{name}.zip"
+
+    puts "[fixtures:download] Downloading #{name}..."
+    FileUtils.mkdir_p(target_dir)
+
+    URI.open(url) do |remote|
+      File.binwrite(zip_file, remote.read)
+    end
+
+    puts "[fixtures:download] Extracting #{name}..."
+    Zip::File.open(zip_file) do |zip|
+      zip.each do |entry|
+        dest_path = File.join(target_dir, entry.name)
+        FileUtils.mkdir_p(File.dirname(dest_path))
+        entry.extract(dest_path) unless File.exist?(dest_path)
+      end
+    end
+
+    FileUtils.rm(zip_file)
+    puts "[fixtures:download] #{name} downloaded successfully"
+  rescue LoadError => e
+    warn "[fixtures:download] Error: Required gem not installed. Please run: gem install rubyzip"
+    raise e
+  end
+
+  # Font configurations with target directories and marker files
+  # All fonts are downloaded via Rake
+  fonts = {
+    "Libertinus" => {
+      url: "https://github.com/alerque/libertinus/releases/download/v7.051/Libertinus-7.051.zip",
+      target_dir: "#{fixtures_dir}/libertinus",
+      marker: "#{fixtures_dir}/libertinus/Libertinus-7.051/static/OTF/LibertinusSerif-Regular.otf",
+    },
+    "MonaSans" => {
+      url: "https://github.com/github/mona-sans/releases/download/v2.0/MonaSans.zip",
+      target_dir: "#{fixtures_dir}/MonaSans",
+      marker: "#{fixtures_dir}/MonaSans/MonaSans/variable/MonaSans[wdth,wght].ttf",
+    },
+    "NotoSerifCJK" => {
+      url: "https://github.com/notofonts/noto-cjk/releases/download/Serif2.003/01_NotoSerifCJK.ttc.zip",
+      target_dir: "#{fixtures_dir}/NotoSerifCJK",
+      marker: "#{fixtures_dir}/NotoSerifCJK/NotoSerifCJK.ttc",
+    },
+    "NotoSerifCJK-VF" => {
+      url: "https://github.com/notofonts/noto-cjk/releases/download/Serif2.003/02_NotoSerifCJK-OTF-VF.zip",
+      target_dir: "#{fixtures_dir}/NotoSerifCJK-VF",
+      marker: "#{fixtures_dir}/NotoSerifCJK-VF/Variable/OTC/NotoSerifCJK-VF.otf.ttc",
+    },
+  }
+
+  # Create file tasks for each font
+  fonts.each do |name, config|
+    file config[:marker] do
+      download_font(name, config[:url], config[:target_dir])
+    end
+  end
+
+  desc "Download all test fixture fonts"
+  task download: fonts.values.map { |config| config[:marker] }
+
+  desc "Clean downloaded fixtures"
+  task :clean do
+    %w[libertinus MonaSans NotoSerifCJK NotoSerifCJK-VF].each do |dir|
+      path = File.join(fixtures_dir, dir)
+      if File.exist?(path)
+        FileUtils.rm_rf(path)
+        puts "[fixtures:clean] Removed #{path}"
+      end
+    end
+  end
+end
+
+# RSpec task depends on fixtures
+RSpec::Core::RakeTask.new(spec: "fixtures:download")
+
+# Default task runs spec and rubocop
+task default: %i[spec rubocop]

data/exe/fontisan

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/fontisan"
+require_relative "../lib/fontisan/cli"
+
+Fontisan::Cli.start(ARGV)

data/fontisan.gemspec

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "lib/fontisan/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "fontisan"
+  spec.version = Fontisan::VERSION
+  spec.authors = ["Ribose Inc."]
+  spec.email = ["open.source@ribose.com"]
+
+  spec.summary = "Font analysis tools and utilities for OpenType fonts"
+  spec.description = <<~HEREDOC
+    Fontisan provides font analysis tools and utilities. It is
+    designed as a pure Ruby implementation with full object-oriented architecture,
+    supporting extraction of information from OpenType and TrueType fonts (OTF, TTF, OTC, TTC).
+
+    The gem provides both a Ruby library API and a command-line interface,
+    with structured output formats (YAML, JSON, text).
+  HEREDOC
+
+  spec.homepage = "https://github.com/fontist/fontisan"
+  spec.license = "BSD-2-Clause"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/fontist/fontisan"
+  spec.metadata["changelog_uri"] = "https://github.com/fontist/fontisan/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "bindata", "~> 2.5"
+  spec.add_dependency "lutaml-model", "~> 0.7"
+  spec.add_dependency "thor", "~> 1.4"
+end

data/lib/fontisan/binary/base_record.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "bindata"
+
+module Fontisan
+  module Binary
+    # Base class for all BinData record definitions
+    #
+    # Provides common configuration for OpenType binary structures:
+    # - Big-endian byte order (OpenType standard)
+    # - Common helper methods
+    #
+    # All table parsers and binary structures should inherit from this class
+    # to ensure consistent behavior across the codebase.
+    #
+    # @example Defining a simple structure
+    #   class MyTable < Binary::BaseRecord
+    #     uint16 :version
+    #     uint16 :count
+    #   end
+    class BaseRecord < BinData::Record
+      endian :big # OpenType uses big-endian byte order
+
+      # Override read to handle nil data gracefully
+      def self.read(io)
+        return new if io.nil? || (io.respond_to?(:empty?) && io.empty?)
+
+        super
+      end
+
+      # Check if the record is valid
+      #
+      # @return [Boolean] True if valid, false otherwise
+      def valid?
+        true
+      end
+
+      private
+
+      # Convert 16.16 fixed-point integer to float
+      #
+      # @param value [Integer] Fixed-point value
+      # @return [Float] Floating-point value
+      def fixed_to_float(value)
+        # Treat as unsigned for the conversion
+        unsigned = value & 0xFFFFFFFF
+        integer_part = (unsigned >> 16) & 0xFFFF
+        fractional_part = unsigned & 0xFFFF
+
+        # Handle sign for the integer part
+        integer_part -= 0x10000 if integer_part >= 0x8000
+
+        integer_part + (fractional_part / 65_536.0)
+      end
+    end
+  end
+end

data/lib/fontisan/binary/structures.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "base_record"
+
+module Fontisan
+  module Binary
+    # OpenType Offset Table (Font Header)
+    #
+    # This structure appears at the beginning of every OpenType font file.
+    # It contains metadata about the table directory.
+    #
+    # Structure:
+    # - uint32: sfnt_version (0x00010000 for TrueType, 'OTTO' for CFF)
+    # - uint16: num_tables (number of tables in font)
+    # - uint16: search_range (maximum power of 2 <= num_tables) * 16
+    # - uint16: entry_selector (log2 of maximum power of 2 <= num_tables)
+    # - uint16: range_shift (num_tables * 16 - search_range)
+    class OffsetTable < BaseRecord
+      uint32 :sfnt_version
+      uint16 :num_tables
+      uint16 :search_range
+      uint16 :entry_selector
+      uint16 :range_shift
+
+      # Check if this is a TrueType font (version 0x00010000 or 'true')
+      #
+      # @return [Boolean] True if TrueType font
+      def truetype?
+        [0x00010000, 0x74727565].include?(sfnt_version) # 'true'
+      end
+
+      # Check if this is an OpenType/CFF font (version 'OTTO')
+      #
+      # @return [Boolean] True if CFF font
+      def cff?
+        sfnt_version == 0x4F54544F # 'OTTO'
+      end
+
+      # Get sfnt version as a tag string
+      #
+      # @return [String] Version tag ('OTTO' or version number)
+      def version_tag
+        if cff?
+          "OTTO"
+        elsif truetype?
+          "TrueType"
+        else
+          format("0x%08X", sfnt_version)
+        end
+      end
+    end
+
+    # OpenType Table Directory Entry
+    #
+    # Each entry describes one table in the font file.
+    #
+    # Structure:
+    # - char[4]: tag (table identifier)
+    # - uint32: checksum (checksum for this table)
+    # - uint32: offset (byte offset from beginning of font file)
+    # - uint32: table_length (length of table in bytes)
+    class TableDirectoryEntry < BaseRecord
+      string :tag, length: 4
+      uint32 :checksum
+      uint32 :offset
+      uint32 :table_length
+
+      # Convert tag to Tag object for comparison
+      #
+      # @return [Parsers::Tag] Tag object
+      def tag_object
+        Parsers::Tag.new(tag)
+      end
+
+      # Check if this entry has a specific tag
+      #
+      # @param other_tag [String, Parsers::Tag] Tag to compare
+      # @return [Boolean] True if tags match
+      def tag?(other_tag)
+        tag_object == (other_tag.is_a?(Parsers::Tag) ? other_tag : Parsers::Tag.new(other_tag))
+      end
+    end
+  end
+end

data/lib/fontisan/cli.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Fontisan
+  # Command-line interface for Fontisan.
+  #
+  # This class provides the Thor-based CLI with commands for extracting
+  # font information and listing tables. It supports multiple output formats
+  # (text, YAML, JSON) and various options for controlling output behavior.
+  #
+  # @example Run the info command
+  #   Fontisan::Cli.start(['info', 'font.ttf'])
+  class Cli < Thor
+    class_option :format, type: :string, default: "text",
+                          desc: "Output format (text, yaml, json)",
+                          aliases: "-f"
+    class_option :font_index, type: :numeric, default: 0,
+                              desc: "Font index for TTC files",
+                              aliases: "-i"
+    class_option :verbose, type: :boolean, default: false,
+                           desc: "Enable verbose output",
+                           aliases: "-v"
+    class_option :quiet, type: :boolean, default: false,
+                         desc: "Suppress non-error output",
+                         aliases: "-q"
+
+    desc "info FONT_FILE", "Display font information"
+    # Extract and display comprehensive font metadata.
+    #
+    # @param font_file [String] Path to the font file
+    def info(font_file)
+      command = Commands::InfoCommand.new(font_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.
+    #
+    # @param font_file [String] Path to the font file
+    def tables(font_file)
+      command = Commands::TablesCommand.new(font_file, options)
+      result = command.run
+      output_result(result)
+    rescue Errno::ENOENT, Error => e
+      handle_error(e)
+    end
+
+    desc "glyphs FONT_FILE", "List glyph names"
+    # List glyph names from the font file.
+    #
+    # @param font_file [String] Path to the font file
+    def glyphs(font_file)
+      command = Commands::GlyphsCommand.new(font_file, options)
+      result = command.run
+      output_result(result)
+    rescue Errno::ENOENT, Error => e
+      handle_error(e)
+    end
+
+    desc "unicode FONT_FILE", "List Unicode to glyph mappings"
+    # List Unicode to glyph index mappings from the font file.
+    #
+    # @param font_file [String] Path to the font file
+    def unicode(font_file)
+      command = Commands::UnicodeCommand.new(font_file, options)
+      result = command.run
+      output_result(result)
+    rescue Errno::ENOENT, Error => e
+      handle_error(e)
+    end
+
+    desc "variable FONT_FILE", "Display variable font information"
+    # Display variable font variation axes and instances.
+    #
+    # @param font_file [String] Path to the font file
+    def variable(font_file)
+      command = Commands::VariableCommand.new(font_file, options)
+      result = command.run
+      output_result(result)
+    rescue Errno::ENOENT, Error => e
+      handle_error(e)
+    end
+
+    desc "optical-size FONT_FILE", "Display optical size information"
+    # Display optical size information from the font file.
+    #
+    # @param font_file [String] Path to the font file
+    def optical_size(font_file)
+      command = Commands::OpticalSizeCommand.new(font_file, options)
+      result = command.run
+      output_result(result)
+    rescue Errno::ENOENT, Error => e
+      handle_error(e)
+    end
+
+    desc "scripts FONT_FILE", "List supported scripts from GSUB/GPOS tables"
+    # List all scripts supported by the font from GSUB and GPOS tables.
+    #
+    # @param font_file [String] Path to the font file
+    def scripts(font_file)
+      command = Commands::ScriptsCommand.new(font_file, options)
+      result = command.run
+      output_result(result)
+    rescue Errno::ENOENT, Error => e
+      handle_error(e)
+    end
+
+    desc "features FONT_FILE", "List GSUB/GPOS features"
+    option :script, type: :string,
+                    desc: "Script tag to query (e.g., latn, cyrl, arab). If not specified, shows features for all scripts",
+                    aliases: "-s"
+    # List OpenType features available for scripts.
+    # If no script is specified, shows features for all scripts.
+    #
+    # @param font_file [String] Path to the font file
+    def features(font_file)
+      command = Commands::FeaturesCommand.new(font_file, options)
+      result = command.run
+      output_result(result)
+    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.
+    #
+    # @param font_file [String] Path to the font file
+    # @param table_tag [String] Four-character table tag (e.g., 'name', 'head')
+    def dump_table(font_file, table_tag)
+      command = Commands::DumpTableCommand.new(font_file, table_tag, options)
+      raw_data = command.run
+
+      # Write binary data directly to stdout
+      $stdout.binmode
+      $stdout.write(raw_data)
+    rescue Errno::ENOENT, Error => e
+      handle_error(e)
+    end
+
+    desc "version", "Display version information"
+    # Display the Fontisan version.
+    def version
+      puts "Fontisan version #{Fontisan::VERSION}"
+    end
+
+    private
+
+    # Output the result in the requested format.
+    #
+    # @param result [Object] The result object to output
+    def output_result(result)
+      output = case options[:format]
+               when "yaml"
+                 result.to_yaml
+               when "json"
+                 result.to_json
+               else
+                 format_as_text(result)
+               end
+
+      puts output unless options[:quiet]
+    end
+
+    # Format result as human-readable text.
+    #
+    # @param result [Object] The result object to format
+    # @return [String] Formatted text output
+    def format_as_text(result)
+      formatter = Formatters::TextFormatter.new
+      formatter.format(result)
+    end
+
+    # Handle errors based on verbosity settings.
+    #
+    # @param error [Error, Errno::ENOENT] The error to handle
+    def handle_error(error)
+      raise error if options[:verbose]
+
+      # Convert Errno::ENOENT to user-friendly message
+      if error.is_a?(Errno::ENOENT)
+      end
+      message = error.message
+
+      warn message unless options[:quiet]
+      exit 1
+    end
+  end
+end

data/lib/fontisan/commands/base_command.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "../font_loader"
+require_relative "../error"
+
+module Fontisan
+  module Commands
+    # Abstract base class for all CLI commands.
+    #
+    # Provides common functionality for loading fonts using FontLoader for
+    # automatic format detection. Works polymorphically with TrueTypeFont
+    # and OpenTypeFont instances.
+    #
+    # Subclasses must implement the `run` method to define command-specific behavior.
+    #
+    # @example Creating a command subclass
+    #   class MyCommand < BaseCommand
+    #     def run
+    #       info = Models::FontInfo.new
+    #       info.family_name = font.table("name").english_name(Tables::Name::FAMILY)
+    #       info
+    #     end
+    #   end
+    class BaseCommand
+      # Initialize a new command with a font file path and options.
+      #
+      # @param font_path [String] Path to the font file
+      # @param options [Hash] Optional command options
+      # @option options [Integer] :font_index Index of font in TTC/OTC collection (default: 0)
+      def initialize(font_path, options = {})
+        @font_path = font_path
+        @options = options
+        @font = load_font
+      end
+
+      # Execute the command.
+      #
+      # This method must be implemented by subclasses.
+      #
+      # @raise [NotImplementedError] if not implemented by subclass
+      # @return [Models::*] Command-specific result as lutaml-model object
+      def run
+        raise NotImplementedError, "Subclasses must implement the run method"
+      end
+
+      protected
+
+      # @!attribute [r] font_path
+      #   @return [String] Path to the font file
+      # @!attribute [r] font
+      #   @return [TrueTypeFont, OpenTypeFont] Loaded font instance
+      # @!attribute [r] options
+      #   @return [Hash] Command options
+      attr_reader :font_path, :font, :options
+
+      private
+
+      # Load the font using FontLoader.
+      #
+      # Uses FontLoader for automatic format detection and loading.
+      # Returns either TrueTypeFont or OpenTypeFont depending on file format.
+      #
+      # @return [TrueTypeFont, OpenTypeFont] The loaded font
+      # @raise [Errno::ENOENT] if file does not exist
+      # @raise [UnsupportedFormatError] for WOFF/WOFF2 or other unsupported formats
+      # @raise [InvalidFontError] for corrupted or unknown formats
+      # @raise [Error] for other loading failures
+      def load_font
+        FontLoader.load(@font_path, font_index: @options[:font_index] || 0)
+      rescue Errno::ENOENT
+        # Re-raise file not found as-is
+        raise
+      rescue UnsupportedFormatError, InvalidFontError
+        # Re-raise format errors as-is
+        raise
+      rescue StandardError => e
+        # Wrap other errors
+        raise Error, "Failed to load font: #{e.message}"
+      end
+    end
+  end
+end

data/lib/fontisan/commands/dump_table_command.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "../font_loader"
+require_relative "../error"
+
+module Fontisan
+  module Commands
+    # Command to dump raw table data from fonts
+    #
+    # This command extracts the binary data of a specific OpenType table
+    # and outputs it directly. This is useful for examining table contents
+    # or extracting tables for external processing.
+    class DumpTableCommand
+      # Initialize a new dump table command
+      #
+      # @param font_path [String] Path to the font file
+      # @param table_tag [String] Four-character table tag (e.g., 'name', 'head')
+      # @param options [Hash] Optional command options
+      # @option options [Integer] :font_index Index of font in TTC/OTC collection (default: 0)
+      def initialize(font_path, table_tag, options = {})
+        @font_path = font_path
+        @table_tag = table_tag
+        @options = options
+        @font = load_font
+      end
+
+      # Execute the dump table command
+      #
+      # @return [String] Raw binary table data
+      # @raise [Error] if table does not exist or data is not available
+      def run
+        unless @font.has_table?(@table_tag)
+          raise Error,
+                "Font does not have '#{@table_tag}' table"
+        end
+
+        # Get raw table data
+        table_data = @font.instance_variable_get(:@table_data)
+        raw_data = table_data[@table_tag]
+
+        unless raw_data
+          raise Error,
+                "Table data not available for '#{@table_tag}'"
+        end
+
+        raw_data
+      end
+
+      private
+
+      attr_reader :font
+
+      # Load the font using FontLoader
+      #
+      # @return [TrueTypeFont, OpenTypeFont] The loaded font
+      # @raise [Errno::ENOENT] if file does not exist
+      # @raise [UnsupportedFormatError] for WOFF/WOFF2 or other unsupported formats
+      # @raise [InvalidFontError] for corrupted or unknown formats
+      # @raise [Error] for other loading failures
+      def load_font
+        FontLoader.load(@font_path, font_index: @options[:font_index] || 0)
+      rescue Errno::ENOENT
+        raise
+      rescue UnsupportedFormatError, InvalidFontError
+        raise
+      rescue StandardError => e
+        raise Error, "Failed to load font: #{e.message}"
+      end
+    end
+  end
+end