fontisan 0.1.0 → 0.2.0

data/lib/fontisan/subset/glyph_mapping.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Subset
+    # Glyph ID mapping management
+    #
+    # This class manages the mapping between original glyph IDs (GIDs) in the
+    # source font and new GIDs in the subset font. It supports two modes:
+    #
+    # 1. Compact mode (retain_gids: false): Glyphs are renumbered sequentially,
+    #    eliminating gaps from removed glyphs. This produces smaller fonts.
+    #
+    # 2. Retain mode (retain_gids: true): Original glyph IDs are preserved,
+    #    with removed glyphs leaving empty slots. This maintains glyph
+    #    references but produces larger fonts.
+    #
+    # @example Compact mode (default)
+    #   mapping = Fontisan::Subset::GlyphMapping.new([0, 5, 10, 15])
+    #   mapping.new_id(5)  # => 1
+    #   mapping.new_id(10) # => 2
+    #   mapping.size       # => 4
+    #
+    # @example Retain mode
+    #   mapping = Fontisan::Subset::GlyphMapping.new([0, 5, 10, 15], retain_gids: true)
+    #   mapping.new_id(5)  # => 5
+    #   mapping.new_id(10) # => 10
+    #   mapping.size       # => 16 (0..15)
+    #
+    # @example Reverse lookup
+    #   mapping = Fontisan::Subset::GlyphMapping.new([0, 5, 10])
+    #   mapping.old_id(1) # => 5
+    class GlyphMapping
+      # @return [Hash<Integer, Integer>] mapping from old GIDs to new GIDs
+      attr_reader :old_to_new
+
+      # @return [Hash<Integer, Integer>] mapping from new GIDs to old GIDs
+      attr_reader :new_to_old
+
+      # @return [Boolean] whether original GIDs are retained
+      attr_reader :retain_gids
+
+      # Initialize glyph mapping
+      #
+      # @param old_glyph_ids [Array<Integer>] array of glyph IDs to include
+      #   in the subset, typically sorted
+      # @param retain_gids [Boolean] whether to preserve original glyph IDs
+      #
+      # @example Create compact mapping
+      #   mapping = GlyphMapping.new([0, 3, 5, 10])
+      #
+      # @example Create mapping that retains GIDs
+      #   mapping = GlyphMapping.new([0, 3, 5, 10], retain_gids: true)
+      def initialize(old_glyph_ids, retain_gids: false)
+        @old_to_new = {}
+        @new_to_old = {}
+        @retain_gids = retain_gids
+
+        build_mappings(old_glyph_ids)
+      end
+
+      # Get new glyph ID for an old glyph ID
+      #
+      # @param old_id [Integer] original glyph ID
+      # @return [Integer, nil] new glyph ID, or nil if not in subset
+      #
+      # @example
+      #   mapping = GlyphMapping.new([0, 5, 10])
+      #   mapping.new_id(5)  # => 1
+      #   mapping.new_id(99) # => nil
+      def new_id(old_id)
+        old_to_new[old_id]
+      end
+
+      # Get old glyph ID for a new glyph ID
+      #
+      # @param new_id [Integer] new glyph ID in subset
+      # @return [Integer, nil] original glyph ID, or nil if invalid
+      #
+      # @example
+      #   mapping = GlyphMapping.new([0, 5, 10])
+      #   mapping.old_id(1) # => 5
+      #   mapping.old_id(99) # => nil
+      def old_id(new_id)
+        new_to_old[new_id]
+      end
+
+      # Get number of glyphs in the subset
+      #
+      # In compact mode, this is the number of included glyphs.
+      # In retain mode, this is the highest old GID + 1.
+      #
+      # @return [Integer] number of glyphs
+      #
+      # @example Compact mode
+      #   mapping = GlyphMapping.new([0, 5, 10])
+      #   mapping.size # => 3
+      #
+      # @example Retain mode
+      #   mapping = GlyphMapping.new([0, 5, 10], retain_gids: true)
+      #   mapping.size # => 11 (0..10)
+      def size
+        new_to_old.size
+      end
+
+      # Check if a glyph is included in the subset
+      #
+      # @param old_id [Integer] original glyph ID to check
+      # @return [Boolean] true if glyph is in subset
+      #
+      # @example
+      #   mapping = GlyphMapping.new([0, 5, 10])
+      #   mapping.include?(5)  # => true
+      #   mapping.include?(99) # => false
+      def include?(old_id)
+        old_to_new.key?(old_id)
+      end
+
+      # Get array of all old glyph IDs in subset
+      #
+      # @return [Array<Integer>] sorted array of old glyph IDs
+      #
+      # @example
+      #   mapping = GlyphMapping.new([10, 0, 5])
+      #   mapping.old_ids # => [0, 5, 10]
+      def old_ids
+        old_to_new.keys.sort
+      end
+
+      # Get array of all new glyph IDs in subset
+      #
+      # @return [Array<Integer>] sorted array of new glyph IDs
+      #
+      # @example
+      #   mapping = GlyphMapping.new([0, 5, 10])
+      #   mapping.new_ids # => [0, 1, 2]
+      def new_ids
+        new_to_old.keys.sort
+      end
+
+      # Iterate over all glyph mappings
+      #
+      # Yields old_id and new_id pairs in order of old glyph IDs.
+      #
+      # @yield [old_id, new_id] each glyph mapping
+      # @yieldparam old_id [Integer] original glyph ID
+      # @yieldparam new_id [Integer] new glyph ID
+      #
+      # @example
+      #   mapping = GlyphMapping.new([0, 5, 10])
+      #   mapping.each do |old_id, new_id|
+      #     puts "#{old_id} => #{new_id}"
+      #   end
+      #   # Output:
+      #   # 0 => 0
+      #   # 5 => 1
+      #   # 10 => 2
+      def each
+        return enum_for(:each) unless block_given?
+
+        old_ids.each do |old_id|
+          yield old_id, old_to_new[old_id]
+        end
+      end
+
+      private
+
+      # Build the bidirectional mapping tables
+      #
+      # @param old_glyph_ids [Array<Integer>] glyph IDs to map
+      def build_mappings(old_glyph_ids)
+        if retain_gids
+          build_retained_mappings(old_glyph_ids)
+        else
+          build_compact_mappings(old_glyph_ids)
+        end
+      end
+
+      # Build mappings in compact mode
+      #
+      # Assigns sequential new GIDs starting from 0, preserving the order
+      # of old GIDs.
+      #
+      # @param old_glyph_ids [Array<Integer>] glyph IDs to map
+      def build_compact_mappings(old_glyph_ids)
+        sorted_ids = old_glyph_ids.sort.uniq
+        sorted_ids.each_with_index do |old_id, new_id|
+          old_to_new[old_id] = new_id
+          new_to_old[new_id] = old_id
+        end
+      end
+
+      # Build mappings in retain GID mode
+      #
+      # Preserves original GIDs, creating empty slots for removed glyphs.
+      #
+      # @param old_glyph_ids [Array<Integer>] glyph IDs to map
+      def build_retained_mappings(old_glyph_ids)
+        sorted_ids = old_glyph_ids.sort.uniq
+        max_id = sorted_ids.max || 0
+
+        # Map each glyph to itself
+        sorted_ids.each do |old_id|
+          old_to_new[old_id] = old_id
+          new_to_old[old_id] = old_id
+        end
+
+        # Fill in empty slots for removed glyphs with nil mappings
+        # This ensures size calculation includes the empty slots
+        (0..max_id).each do |gid|
+          new_to_old[gid] ||= nil
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/subset/options.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Subset
+    # Subsetting configuration class
+    #
+    # This class defines all available options for font subsetting operations.
+    # It provides sensible defaults for various subsetting scenarios and uses
+    # Lutaml::Model for serialization support.
+    #
+    # @example Create default PDF subsetting options
+    #   options = Fontisan::Subset::Options.new
+    #   options.profile # => "pdf"
+    #   options.drop_hints # => false
+    #
+    # @example Create custom web subsetting options
+    #   options = Fontisan::Subset::Options.new(
+    #     profile: "web",
+    #     drop_hints: true,
+    #     unicode_ranges: false
+    #   )
+    #
+    # @example Retain original glyph IDs
+    #   options = Fontisan::Subset::Options.new(retain_gids: true)
+    class Options < Lutaml::Model::Serializable
+      # Subsetting profile name (pdf, web, minimal, or custom)
+      #
+      # @return [String] the profile name
+      attribute :profile, :string, default: -> { "pdf" }
+
+      # Whether to drop hinting instructions
+      #
+      # Hinting improves text rendering at small sizes but increases file size.
+      # Web fonts typically don't need hints due to modern rendering engines.
+      #
+      # @return [Boolean] true to drop hints, false to retain them
+      attribute :drop_hints, :boolean, default: -> { false }
+
+      # Whether to drop glyph names from the post table
+      #
+      # Glyph names are useful for debugging but not required for rendering.
+      # Dropping them reduces file size.
+      #
+      # @return [Boolean] true to drop names, false to retain them
+      attribute :drop_names, :boolean, default: -> { false }
+
+      # Whether to prune OS/2 Unicode ranges
+      #
+      # Updates the OS/2 table's Unicode range bits to reflect only the
+      # glyphs present in the subset.
+      #
+      # @return [Boolean] true to prune ranges, false to keep original
+      attribute :unicode_ranges, :boolean, default: -> { true }
+
+      # Whether to retain original glyph IDs
+      #
+      # When true, removed glyphs leave empty slots in the glyf table,
+      # preserving original GID assignments. When false, glyphs are
+      # compacted to eliminate gaps.
+      #
+      # @return [Boolean] true to retain GIDs, false to compact
+      attribute :retain_gids, :boolean, default: -> { false }
+
+      # Whether to include the .notdef glyph
+      #
+      # The .notdef glyph is displayed for missing characters. It is
+      # typically required by font specifications.
+      #
+      # @return [Boolean] true to include .notdef, false to exclude
+      attribute :include_notdef, :boolean, default: -> { true }
+
+      # Whether to include the .null glyph
+      #
+      # The .null glyph (U+0000) is sometimes used for control purposes.
+      #
+      # @return [Boolean] true to include .null, false to exclude
+      attribute :include_null, :boolean, default: -> { false }
+
+      # OpenType features to retain in the subset
+      #
+      # An empty array means all features are retained. Specify feature
+      # tags (e.g., ['liga', 'kern']) to keep only those features.
+      #
+      # @return [Array<String>] array of feature tags to retain
+      attribute :features, :string, collection: true, default: -> { [] }
+
+      # Script tags to retain in the subset
+      #
+      # An array containing "*" means all scripts are retained. Specify
+      # script tags (e.g., ['latn', 'arab']) to keep only those scripts.
+      #
+      # @return [Array<String>] array of script tags to retain
+      attribute :scripts, :string, collection: true, default: -> { ["*"] }
+
+      # Initialize options with custom values
+      #
+      # @param attributes [Hash] hash of attribute values
+      # @option attributes [String] :profile ("pdf") subsetting profile
+      # @option attributes [Boolean] :drop_hints (false) drop hinting
+      # @option attributes [Boolean] :drop_names (false) drop glyph names
+      # @option attributes [Boolean] :unicode_ranges (true) prune OS/2 ranges
+      # @option attributes [Boolean] :retain_gids (false) retain glyph IDs
+      # @option attributes [Boolean] :include_notdef (true) include .notdef
+      # @option attributes [Boolean] :include_null (false) include .null
+      # @option attributes [Array<String>] :features ([]) features to keep
+      # @option attributes [Array<String>] :scripts (["*"]) scripts to keep
+      def initialize(attributes = {})
+        super
+      end
+
+      # Check if all features should be retained
+      #
+      # @return [Boolean] true if features array is empty
+      def all_features?
+        features.empty?
+      end
+
+      # Check if all scripts should be retained
+      #
+      # @return [Boolean] true if scripts contains "*"
+      def all_scripts?
+        scripts.include?("*")
+      end
+
+      # Validate the options configuration
+      #
+      # @raise [ArgumentError] if profile is invalid
+      # @return [Boolean] true if valid
+      def validate!
+        valid_profiles = %w[pdf web minimal custom]
+        unless valid_profiles.include?(profile)
+          raise ArgumentError,
+                "Invalid profile '#{profile}'. Must be one of: #{valid_profiles.join(', ')}"
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/fontisan/subset/profile.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Fontisan
+  module Subset
+    # Subsetting profiles
+    #
+    # This class manages font subsetting profiles that specify which
+    # font tables should be included in the subset. Profiles are loaded from
+    # an external YAML configuration file for flexibility and maintainability.
+    #
+    # @example Get tables for PDF profile
+    #   tables = Fontisan::Subset::Profile.for_name("pdf")
+    #   # => ["cmap", "head", "hhea", "hmtx", "maxp", "name", "post", "loca", "glyf"]
+    #
+    # @example Get tables for web profile
+    #   tables = Fontisan::Subset::Profile.for_name("web")
+    #   # => ["cmap", "head", "hhea", "hmtx", "maxp", "name", "OS/2", "post", "loca", "glyf"]
+    #
+    # @example Create custom profile
+    #   tables = Fontisan::Subset::Profile.custom(["cmap", "head", "hhea"])
+    #   # => ["cmap", "head", "hhea"]
+    class Profile
+      # All known font table tags
+      #
+      # Comprehensive list of all standard TrueType/OpenType tables
+      KNOWN_TABLES = %w[
+        cmap head hhea hmtx maxp name OS/2 post
+        loca glyf cvt fpgm prep gasp
+        GSUB GPOS GDEF BASE JSTF
+        CFF CFF2 VORG
+        EBDT EBLC EBSC
+        CBDT CBLC sbix
+        kern vhea vmtx
+        LTSH PCLT VDMX hdmx
+        fvar gvar avar cvar HVAR VVAR MVAR STAT
+        DSIG
+      ].freeze
+
+      class << self
+        # Get table list for a named profile
+        #
+        # @param name [String] profile name (pdf, web, minimal, full)
+        # @raise [ArgumentError] if profile name is unknown
+        # @return [Array<String>] array of table tags
+        #
+        # @example
+        #   Profile.for_name("pdf")
+        #   # => ["cmap", "head", "hhea", "hmtx", "maxp", "name", "post", "loca", "glyf"]
+        def for_name(name)
+          profiles = load_profiles
+          profile_config = profiles[name.to_s.downcase]
+
+          unless profile_config
+            raise ArgumentError,
+                  "Unknown profile '#{name}'. Valid profiles: #{valid_names.join(', ')}"
+          end
+
+          profile_config["tables"].dup
+        end
+
+        # Create a custom profile with specified tables
+        #
+        # Validates that all provided table tags are recognized and returns
+        # the list of tables in a consistent format.
+        #
+        # @param tables [Array<String>] array of table tags
+        # @raise [ArgumentError] if any table tag is unknown
+        # @return [Array<String>] validated array of table tags
+        #
+        # @example Create custom profile
+        #   Profile.custom(["cmap", "head", "glyf"])
+        #   # => ["cmap", "head", "glyf"]
+        #
+        # @example Invalid table raises error
+        #   Profile.custom(["cmap", "invalid"])
+        #   # => ArgumentError: Unknown table tags: invalid
+        def custom(tables)
+          tables = Array(tables)
+          unknown = tables - KNOWN_TABLES
+
+          unless unknown.empty?
+            raise ArgumentError,
+                  "Unknown table tags: #{unknown.join(', ')}"
+          end
+
+          tables.dup
+        end
+
+        # Check if a table tag is recognized
+        #
+        # @param table [String] table tag to check
+        # @return [Boolean] true if table is known
+        #
+        # @example
+        #   Profile.known_table?("cmap") # => true
+        #   Profile.known_table?("invalid") # => false
+        def known_table?(table)
+          KNOWN_TABLES.include?(table.to_s)
+        end
+
+        # Get list of all valid profile names
+        #
+        # @return [Array<String>] array of profile names
+        #
+        # @example
+        #   Profile.valid_names # => ["pdf", "web", "minimal", "full"]
+        def valid_names
+          load_profiles.keys.sort
+        end
+
+        # Get profile description
+        #
+        # @param name [String] profile name
+        # @return [String, nil] profile description or nil if not found
+        #
+        # @example
+        #   Profile.description("pdf")
+        #   # => "Minimal tables required for PDF font embedding"
+        def description(name)
+          profiles = load_profiles
+          profile_config = profiles[name.to_s.downcase]
+          profile_config&.dig("description")
+        end
+
+        private
+
+        # Load profiles from YAML configuration file
+        #
+        # @return [Hash] Hash of profile configurations
+        def load_profiles
+          @load_profiles ||= begin
+            config_path = File.join(__dir__, "../config/subset_profiles.yml")
+            YAML.load_file(config_path)
+          rescue Errno::ENOENT
+            raise Fontisan::Error,
+                  "Profile configuration file not found: #{config_path}"
+          rescue Psych::SyntaxError => e
+            raise Fontisan::Error,
+                  "Invalid YAML in profile configuration: #{e.message}"
+          end
+        end
+
+        # Clear cached profiles (useful for testing)
+        def clear_cache!
+          @load_profiles = nil
+        end
+      end
+    end
+  end
+end