fontisan 0.1.0 → 0.2.0

data/lib/fontisan/tables/cff/index_builder.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Fontisan
+  module Tables
+    class Cff
+      # CFF INDEX structure builder
+      #
+      # [`IndexBuilder`](lib/fontisan/tables/cff/index_builder.rb) constructs
+      # binary INDEX structures from arrays of data items. INDEX is a fundamental
+      # CFF data structure used for storing arrays of variable-length data.
+      #
+      # The builder calculates optimal offset sizes, constructs the offset array,
+      # and produces compact binary output.
+      #
+      # Structure produced:
+      # - count (Card16): Number of items
+      # - offSize (OffSize): Size of offset values (1-4 bytes)
+      # - offset[count+1] (Offset): Array of offsets to data
+      # - data: Concatenated data bytes
+      #
+      # Offsets are 1-based (first offset is always 1). The last offset points
+      # one byte past the end of the data.
+      #
+      # Reference: CFF specification section 5 "INDEX Data"
+      # https://adobe-type-tools.github.io/font-tech-notes/pdfs/5176.CFF.pdf
+      #
+      # @example Building an INDEX
+      #   items = ["data1".b, "data2".b, "data3".b]
+      #   index_data = Fontisan::Tables::Cff::IndexBuilder.build(items)
+      class IndexBuilder
+        # Build INDEX structure from array of binary strings
+        #
+        # @param items [Array<String>] Array of binary data items
+        # @return [String] Binary INDEX data
+        # @raise [ArgumentError] If items is not an Array
+        def self.build(items)
+          validate_items!(items)
+
+          return build_empty_index if items.empty?
+
+          # Calculate total data size
+          data_size = items.sum(&:bytesize)
+
+          # Calculate optimal offset size (1-4 bytes)
+          # Last offset will be data_size + 1 (1-based)
+          off_size = calculate_off_size(data_size + 1)
+
+          # Build offset array (count + 1 offsets)
+          offsets = build_offsets(items, off_size)
+
+          # Concatenate all data
+          data = items.join
+
+          # Assemble INDEX structure
+          output = StringIO.new("".b)
+
+          # Write count (Card16)
+          output.write([items.length].pack("n"))
+
+          # Write offSize (OffSize)
+          output.putc(off_size)
+
+          # Write offset array
+          offsets.each do |offset|
+            write_offset(output, offset, off_size)
+          end
+
+          # Write data
+          output.write(data)
+
+          output.string
+        end
+
+        # Build an empty INDEX (count = 0)
+        #
+        # @return [String] Binary empty INDEX
+        def self.build_empty_index
+          # Empty INDEX has only count field (0)
+          [0].pack("n")
+        end
+        private_class_method :build_empty_index
+
+        # Validate items parameter
+        #
+        # @param items [Object] Items to validate
+        # @raise [ArgumentError] If items is invalid
+        def self.validate_items!(items)
+          raise ArgumentError, "items must be Array" unless items.is_a?(Array)
+
+          items.each_with_index do |item, i|
+            unless item.is_a?(String)
+              raise ArgumentError,
+                    "item #{i} must be String, got: #{item.class}"
+            end
+            unless item.encoding == ::Encoding::BINARY
+              raise ArgumentError,
+                    "item #{i} must have BINARY encoding, got: #{item.encoding}"
+            end
+          end
+        end
+        private_class_method :validate_items!
+
+        # Calculate optimal offset size for given maximum offset
+        #
+        # @param max_offset [Integer] Maximum offset value
+        # @return [Integer] Offset size (1-4 bytes)
+        def self.calculate_off_size(max_offset)
+          return 1 if max_offset <= 0xFF
+          return 2 if max_offset <= 0xFFFF
+          return 3 if max_offset <= 0xFFFFFF
+
+          4
+        end
+        private_class_method :calculate_off_size
+
+        # Build offset array from items
+        #
+        # Offsets are 1-based. First offset is always 1.
+        # Each offset points to the start of its item in the data array.
+        # Last offset points one byte past the end of data.
+        #
+        # @param items [Array<String>] Array of data items
+        # @param off_size [Integer] Offset size (1-4 bytes)
+        # @return [Array<Integer>] Array of offsets (count + 1 elements)
+        def self.build_offsets(items, _off_size)
+          offsets = []
+          current_offset = 1 # 1-based
+
+          # First offset is always 1
+          offsets << current_offset
+
+          # Calculate offset for each item
+          items.each do |item|
+            current_offset += item.bytesize
+            offsets << current_offset
+          end
+
+          offsets
+        end
+        private_class_method :build_offsets
+
+        # Write an offset value of specified size
+        #
+        # @param io [StringIO] Output stream
+        # @param offset [Integer] Offset value to write
+        # @param size [Integer] Number of bytes (1-4)
+        def self.write_offset(io, offset, size)
+          case size
+          when 1
+            io.putc(offset & 0xFF)
+          when 2
+            io.write([offset].pack("n")) # Big-endian unsigned 16-bit
+          when 3
+            # 24-bit big-endian
+            io.putc((offset >> 16) & 0xFF)
+            io.putc((offset >> 8) & 0xFF)
+            io.putc(offset & 0xFF)
+          when 4
+            io.write([offset].pack("N")) # Big-endian unsigned 32-bit
+          else
+            raise ArgumentError, "Invalid offset size: #{size}"
+          end
+        end
+        private_class_method :write_offset
+      end
+    end
+  end
+end

data/lib/fontisan/tables/cff/private_dict.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+require_relative "dict"
+
+module Fontisan
+  module Tables
+    class Cff
+      # CFF Private DICT structure
+      #
+      # The Private DICT contains glyph-specific hinting and width data.
+      # Each font has its own Private DICT (or multiple for CIDFonts).
+      #
+      # Private DICT Operators:
+      # - blue_values: Alignment zones for overshoot suppression
+      # - other_blues: Additional alignment zones
+      # - family_blues: Family-wide alignment zones
+      # - family_other_blues: Family-wide additional alignment zones
+      # - blue_scale: Point size for overshoot suppression
+      # - blue_shift: Pixels to shift alignment zones
+      # - blue_fuzz: Tolerance for alignment zones
+      # - std_hw: Standard horizontal stem width
+      # - std_vw: Standard vertical stem width
+      # - stem_snap_h: Horizontal stem snap widths
+      # - stem_snap_v: Vertical stem snap widths
+      # - force_bold: Force bold flag
+      # - language_group: Language group (0=Latin, 1=CJK)
+      # - expansion_factor: Expansion factor for counters
+      # - initial_random_seed: Random seed for Type 1 hinting
+      # - subrs: Offset to Local Subr INDEX (relative to Private DICT)
+      # - default_width_x: Default glyph width
+      # - nominal_width_x: Nominal glyph width
+      #
+      # Reference: CFF specification section 10 "Private DICT"
+      # https://adobe-type-tools.github.io/font-tech-notes/pdfs/5176.CFF.pdf
+      #
+      # @example Parsing a Private DICT
+      #   private_size, private_offset = top_dict.private
+      #   private_data = cff.raw_data[private_offset, private_size]
+      #   private_dict = Fontisan::Tables::Cff::PrivateDict.new(private_data)
+      #   puts private_dict[:blue_values]  # => [array of blue values]
+      #   puts private_dict.default_width_x  # => default glyph width
+      class PrivateDict < Dict
+        # Private DICT specific operators
+        #
+        # These extend the common operators defined in the base Dict class
+        PRIVATE_DICT_OPERATORS = {
+          6 => :blue_values,
+          7 => :other_blues,
+          8 => :family_blues,
+          9 => :family_other_blues,
+          [12, 9] => :blue_scale,
+          [12, 10] => :blue_shift,
+          [12, 11] => :blue_fuzz,
+          10 => :std_hw,
+          11 => :std_vw,
+          [12, 12] => :stem_snap_h,
+          [12, 13] => :stem_snap_v,
+          [12, 14] => :force_bold,
+          [12, 17] => :language_group,
+          [12, 18] => :expansion_factor,
+          [12, 19] => :initial_random_seed,
+          19 => :subrs,
+          20 => :default_width_x,
+          21 => :nominal_width_x,
+        }.freeze
+
+        # Default values for Private DICT operators
+        #
+        # These are used when an operator is not present in the DICT
+        DEFAULTS = {
+          blue_scale: 0.039625,
+          blue_shift: 7,
+          blue_fuzz: 1,
+          force_bold: false,
+          language_group: 0,
+          expansion_factor: 0.06,
+          initial_random_seed: 0,
+          default_width_x: 0,
+          nominal_width_x: 0,
+        }.freeze
+
+        # Get a value with default fallback
+        #
+        # @param key [Symbol] Operator name
+        # @return [Object] Value or default value
+        def fetch(key, default = nil)
+          @dict.fetch(key, DEFAULTS.fetch(key, default))
+        end
+
+        # Get the blue values (alignment zones)
+        #
+        # Blue values define vertical zones for overshoot suppression
+        #
+        # @return [Array<Integer>, nil] Array of blue values (pairs of bottom/top)
+        def blue_values
+          @dict[:blue_values]
+        end
+
+        # Get the other blue values
+        #
+        # Additional alignment zones beyond the baseline and cap height
+        #
+        # @return [Array<Integer>, nil] Array of other blue values
+        def other_blues
+          @dict[:other_blues]
+        end
+
+        # Get the family blue values
+        #
+        # Family-wide alignment zones shared across fonts in a family
+        #
+        # @return [Array<Integer>, nil] Array of family blue values
+        def family_blues
+          @dict[:family_blues]
+        end
+
+        # Get the family other blue values
+        #
+        # @return [Array<Integer>, nil] Array of family other blue values
+        def family_other_blues
+          @dict[:family_other_blues]
+        end
+
+        # Get the blue scale
+        #
+        # Point size at which overshoot suppression is maximum
+        #
+        # @return [Float] Blue scale value
+        def blue_scale
+          fetch(:blue_scale)
+        end
+
+        # Get the blue shift
+        #
+        # Number of device pixels to shift alignment zones
+        #
+        # @return [Integer] Blue shift in pixels
+        def blue_shift
+          fetch(:blue_shift)
+        end
+
+        # Get the blue fuzz
+        #
+        # Tolerance for alignment zone matching
+        #
+        # @return [Integer] Blue fuzz in font units
+        def blue_fuzz
+          fetch(:blue_fuzz)
+        end
+
+        # Get the standard horizontal width
+        #
+        # Dominant horizontal stem width
+        #
+        # @return [Integer, nil] Standard horizontal width
+        def std_hw
+          value = @dict[:std_hw]
+          # std_hw is stored as an array with one element
+          value.is_a?(Array) ? value.first : value
+        end
+
+        # Get the standard vertical width
+        #
+        # Dominant vertical stem width
+        #
+        # @return [Integer, nil] Standard vertical width
+        def std_vw
+          value = @dict[:std_vw]
+          # std_vw is stored as an array with one element
+          value.is_a?(Array) ? value.first : value
+        end
+
+        # Get the horizontal stem snap widths
+        #
+        # Array of horizontal stem widths for stem snapping
+        #
+        # @return [Array<Integer>, nil] Horizontal stem snap widths
+        def stem_snap_h
+          @dict[:stem_snap_h]
+        end
+
+        # Get the vertical stem snap widths
+        #
+        # Array of vertical stem widths for stem snapping
+        #
+        # @return [Array<Integer>, nil] Vertical stem snap widths
+        def stem_snap_v
+          @dict[:stem_snap_v]
+        end
+
+        # Check if force bold is enabled
+        #
+        # @return [Boolean] True if force bold is enabled
+        def force_bold?
+          fetch(:force_bold)
+        end
+
+        # Get the language group
+        #
+        # 0 = Latin/Greek/Cyrillic, 1 = CJK
+        #
+        # @return [Integer] Language group (0 or 1)
+        def language_group
+          fetch(:language_group)
+        end
+
+        # Get the expansion factor
+        #
+        # Controls horizontal counter expansion
+        #
+        # @return [Float] Expansion factor
+        def expansion_factor
+          fetch(:expansion_factor)
+        end
+
+        # Get the initial random seed
+        #
+        # Seed for pseudo-random number generation in Type 1 hinting
+        #
+        # @return [Integer] Initial random seed
+        def initial_random_seed
+          fetch(:initial_random_seed)
+        end
+
+        # Get the Local Subr INDEX offset
+        #
+        # Offset is relative to the beginning of the Private DICT
+        #
+        # @return [Integer, nil] Offset to Local Subr INDEX
+        def subrs
+          @dict[:subrs]
+        end
+
+        # Get the default glyph width
+        #
+        # Used when width is not explicitly specified in CharString
+        #
+        # @return [Integer] Default width in font units
+        def default_width_x
+          fetch(:default_width_x)
+        end
+
+        # Get the nominal glyph width
+        #
+        # Base value for width calculations in CharStrings
+        #
+        # @return [Integer] Nominal width in font units
+        def nominal_width_x
+          fetch(:nominal_width_x)
+        end
+
+        # Check if this Private DICT has local subroutines
+        #
+        # @return [Boolean] True if subrs offset is present
+        def has_local_subrs?
+          !subrs.nil?
+        end
+
+        # Check if this Private DICT has blue values defined
+        #
+        # @return [Boolean] True if blue values are present
+        def has_blue_values?
+          !blue_values.nil? && !blue_values.empty?
+        end
+
+        # Check if this is for CJK language group
+        #
+        # @return [Boolean] True if language group is 1 (CJK)
+        def cjk?
+          language_group == 1
+        end
+
+        private
+
+        # Get Private DICT specific operators
+        #
+        # @return [Hash] Private DICT operators merged with base operators
+        def derived_operators
+          PRIVATE_DICT_OPERATORS
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/tables/cff/top_dict.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require_relative "dict"
+
+module Fontisan
+  module Tables
+    class Cff
+      # CFF Top DICT structure
+      #
+      # The Top DICT contains font-level metadata and pointers to other CFF
+      # structures like CharStrings, Charset, Encoding, and Private DICT.
+      #
+      # Top DICT Operators (in addition to common DICT operators):
+      # - charset: Offset to Charset data
+      # - encoding: Offset to Encoding data
+      # - charstrings: Offset to CharStrings INDEX
+      # - private: Size and offset to Private DICT
+      # - font_bbox: Font bounding box [xMin, yMin, xMax, yMax]
+      # - unique_id: Unique ID for this font
+      # - xuid: Extended unique ID array
+      # - ros: CIDFont registry, ordering, supplement
+      # - cidcount: Number of CIDs in CIDFont
+      # - fdarray: Offset to Font DICT INDEX (CIDFont)
+      # - fdselect: Offset to FDSelect data (CIDFont)
+      #
+      # Reference: CFF specification section 9 "Top DICT"
+      # https://adobe-type-tools.github.io/font-tech-notes/pdfs/5176.CFF.pdf
+      #
+      # @example Parsing a Top DICT
+      #   top_dict_data = cff.top_dict_index[0]
+      #   top_dict = Fontisan::Tables::Cff::TopDict.new(top_dict_data)
+      #   puts top_dict[:charstrings]  # => offset to CharStrings
+      #   puts top_dict[:charset]      # => offset to Charset
+      class TopDict < Dict
+        # Top DICT specific operators
+        #
+        # These extend the common operators defined in the base Dict class
+        TOP_DICT_OPERATORS = {
+          5 => :font_bbox,
+          13 => :unique_id,
+          14 => :xuid,
+          15 => :charset,
+          16 => :encoding,
+          17 => :charstrings,
+          18 => :private,
+          [12, 30] => :ros,
+          [12, 31] => :cid_font_version,
+          [12, 32] => :cid_font_revision,
+          [12, 33] => :cid_font_type,
+          [12, 34] => :cid_count,
+          [12, 35] => :uid_base,
+          [12, 36] => :fd_array,
+          [12, 37] => :fd_select,
+          [12, 38] => :font_name,
+        }.freeze
+
+        # Default values for Top DICT operators
+        #
+        # These are used when an operator is not present in the DICT
+        DEFAULTS = {
+          is_fixed_pitch: false,
+          italic_angle: 0,
+          underline_position: -100,
+          underline_thickness: 50,
+          paint_type: 0,
+          charstring_type: 2,
+          font_matrix: [0.001, 0, 0, 0.001, 0, 0],
+          unique_id: nil,
+          font_bbox: [0, 0, 0, 0],
+          stroke_width: 0,
+          charset: 0,       # Offset 0 = ISOAdobe charset
+          encoding: 0,      # Offset 0 = Standard encoding
+          cid_count: 8720,
+        }.freeze
+
+        # Get a value with default fallback
+        #
+        # @param key [Symbol] Operator name
+        # @return [Object] Value or default value
+        def fetch(key, default = nil)
+          @dict.fetch(key, DEFAULTS.fetch(key, default))
+        end
+
+        # Get the charset offset
+        #
+        # Charset determines which glyphs are present and their SIDs
+        #
+        # Special values:
+        # - 0: ISOAdobe charset
+        # - 1: Expert charset
+        # - 2: Expert Subset charset
+        # - Otherwise: Offset to custom charset
+        #
+        # @return [Integer] Charset offset or predefined charset ID
+        def charset
+          fetch(:charset)
+        end
+
+        # Get the encoding offset
+        #
+        # Encoding maps character codes to glyph indices
+        #
+        # Special values:
+        # - 0: Standard encoding
+        # - 1: Expert encoding
+        # - Otherwise: Offset to custom encoding
+        #
+        # @return [Integer] Encoding offset or predefined encoding ID
+        def encoding
+          fetch(:encoding)
+        end
+
+        # Get the CharStrings offset
+        #
+        # CharStrings INDEX contains the glyph programs (outline data)
+        #
+        # @return [Integer, nil] Offset to CharStrings INDEX
+        def charstrings
+          @dict[:charstrings]
+        end
+
+        # Get the Private DICT size and offset
+        #
+        # The private operator stores [size, offset] as a two-element array
+        #
+        # @return [Array<Integer>, nil] [size, offset] or nil if not present
+        def private
+          @dict[:private]
+        end
+
+        # Get the Private DICT size
+        #
+        # @return [Integer, nil] Size in bytes, or nil if no Private DICT
+        def private_size
+          private&.first
+        end
+
+        # Get the Private DICT offset
+        #
+        # @return [Integer, nil] Offset in bytes, or nil if no Private DICT
+        def private_offset
+          private&.last
+        end
+
+        # Get the font bounding box
+        #
+        # @return [Array<Integer>] [xMin, yMin, xMax, yMax]
+        def font_bbox
+          fetch(:font_bbox)
+        end
+
+        # Get the font matrix
+        #
+        # Transform from glyph space to user space
+        #
+        # @return [Array<Float>] 6-element affine transformation matrix
+        def font_matrix
+          fetch(:font_matrix)
+        end
+
+        # Check if this is a CIDFont
+        #
+        # CIDFonts have the ROS (Registry-Ordering-Supplement) operator
+        #
+        # @return [Boolean] True if CIDFont
+        def cid_font?
+          has_key?(:ros)
+        end
+
+        # Get the ROS (Registry, Ordering, Supplement) for CIDFonts
+        #
+        # @return [Array<Integer>, nil] [registry_sid, ordering_sid, supplement]
+        def ros
+          @dict[:ros]
+        end
+
+        # Get the CID count for CIDFonts
+        #
+        # @return [Integer] Number of CIDs
+        def cid_count
+          fetch(:cid_count)
+        end
+
+        # Get the FDArray offset for CIDFonts
+        #
+        # FDArray is a Font DICT INDEX for CIDFonts
+        #
+        # @return [Integer, nil] Offset to FDArray
+        def fd_array
+          @dict[:fd_array]
+        end
+
+        # Get the FDSelect offset for CIDFonts
+        #
+        # FDSelect maps CIDs to Font DICTs in FDArray
+        #
+        # @return [Integer, nil] Offset to FDSelect
+        def fd_select
+          @dict[:fd_select]
+        end
+
+        # Get the CharString type
+        #
+        # @return [Integer] CharString type (typically 2 for Type 2 CharStrings)
+        def charstring_type
+          fetch(:charstring_type)
+        end
+
+        # Check if the font has a custom charset
+        #
+        # @return [Boolean] True if charset is custom (not 0, 1, or 2)
+        def custom_charset?
+          charset_val = charset
+          charset_val && charset_val > 2
+        end
+
+        # Check if the font has a custom encoding
+        #
+        # @return [Boolean] True if encoding is custom (not 0 or 1)
+        def custom_encoding?
+          encoding_val = encoding
+          encoding_val && encoding_val > 1
+        end
+
+        private
+
+        # Get Top DICT specific operators
+        #
+        # @return [Hash] Top DICT operators merged with base operators
+        def derived_operators
+          TOP_DICT_OPERATORS
+        end
+      end
+    end
+  end
+end