fontisan 0.1.0 → 0.2.1

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

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require_relative "../../models/hint"
+
+module Fontisan
+  module Tables
+    class Cff
+      # Injects hint operations into CharString operation lists
+      #
+      # HintOperationInjector converts abstract Hint objects into CFF CharString
+      # operations and injects them at the appropriate position. It handles:
+      # - Stem hints (hstem, vstem, hstemhm, vstemhm)
+      # - Hint masks (hintmask with mask data)
+      # - Counter masks (cntrmask with mask data)
+      # - Stack management (hints are stack-neutral)
+      #
+      # **Position Rules:**
+      # - Hints must appear BEFORE any path construction operators
+      # - Width (if present) comes first
+      # - Stem hints come before hintmask/cntrmask
+      # - Once path construction begins, no more hints allowed
+      #
+      # **Stack Neutrality:**
+      # - Hint operators consume their operands
+      # - They don't leave anything on the stack
+      # - Path construction starts with clean stack
+      #
+      # Reference: Type 2 CharString Format Section 4
+      # Adobe Technical Note #5177
+      #
+      # @example Inject hints into a glyph
+      #   injector = HintOperationInjector.new
+      #   hints = [
+      #     Hint.new(type: :stem, data: { position: 100, width: 50, orientation: :horizontal })
+      #   ]
+      #   modified_ops = injector.inject(hints, original_operations)
+      class HintOperationInjector
+        # Initialize injector
+        def initialize
+          @stem_count = 0
+        end
+
+        # Inject hint operations into operation list
+        #
+        # @param hints [Array<Models::Hint>] Hints to inject
+        # @param operations [Array<Hash>] Original CharString operations
+        # @return [Array<Hash>] Modified operations with hints injected
+        def inject(hints, operations)
+          return operations if hints.nil? || hints.empty?
+
+          # Convert hints to operations
+          hint_ops = convert_hints_to_operations(hints)
+          return operations if hint_ops.empty?
+
+          # Find injection point (before first path operator)
+          inject_index = find_injection_point(operations)
+
+          # Insert hint operations
+          operations.dup.insert(inject_index, *hint_ops)
+        end
+
+        # Get stem count after injection (needed for hintmask)
+        #
+        # @return [Integer] Number of stem hints
+        attr_reader :stem_count
+
+        private
+
+        # Convert Hint objects to CharString operations
+        #
+        # @param hints [Array<Models::Hint>] Hints to convert
+        # @return [Array<Hash>] CharString operations
+        def convert_hints_to_operations(hints)
+          operations = []
+          @stem_count = 0
+
+          hints.each do |hint|
+            ops = hint_to_operations(hint)
+            operations.concat(ops)
+          end
+
+          operations
+        end
+
+        # Convert single Hint to operations
+        #
+        # @param hint [Models::Hint] Hint object
+        # @return [Array<Hash>] CharString operations
+        def hint_to_operations(hint)
+          ps_hint = hint.to_postscript
+          return [] if ps_hint.empty?
+
+          case ps_hint[:operator]
+          when :hstem, :vstem
+            stem_operation(ps_hint)
+          when :hstemhm, :vstemhm
+            stem_operation(ps_hint)
+          when :hintmask
+            hintmask_operation(ps_hint)
+          when :counter, :cntrmask
+            # :counter from Hint model maps to :cntrmask in CharStrings
+            cntrmask_operation(ps_hint)
+          else
+            []
+          end
+        end
+
+        # Create stem hint operation
+        #
+        # @param ps_hint [Hash] PostScript hint with :operator and :args
+        # @return [Array<Hash>] CharString operations
+        def stem_operation(ps_hint)
+          operator = ps_hint[:operator]
+          args = ps_hint[:args] || []
+
+          # Each pair of args is one stem
+          @stem_count += args.length / 2
+
+          [{
+            type: :operator,
+            name: operator,
+            operands: args,
+            hint_data: nil
+          }]
+        end
+
+        # Create hintmask operation
+        #
+        # @param ps_hint [Hash] PostScript hint with :operator and :args (mask)
+        # @return [Array<Hash>] CharString operations
+        def hintmask_operation(ps_hint)
+          mask_bytes = ps_hint[:args] || []
+
+          # Convert mask array to binary string
+          hint_data = if mask_bytes.is_a?(Array)
+                        mask_bytes.pack("C*")
+                      elsif mask_bytes.is_a?(String)
+                        mask_bytes
+                      else
+                        ""
+                      end
+
+          [{
+            type: :operator,
+            name: :hintmask,
+            operands: [],
+            hint_data: hint_data
+          }]
+        end
+
+        # Create cntrmask operation
+        #
+        # @param ps_hint [Hash] PostScript hint with :operator and :args (zones)
+        # @return [Array<Hash>] CharString operations
+        def cntrmask_operation(ps_hint)
+          zones = ps_hint[:args] || []
+
+          # Convert zones to binary string
+          hint_data = if zones.is_a?(Array)
+                        zones.pack("C*")
+                      elsif zones.is_a?(String)
+                        zones
+                      else
+                        ""
+                      end
+
+          [{
+            type: :operator,
+            name: :cntrmask,
+            operands: [],
+            hint_data: hint_data
+          }]
+        end
+
+        # Find injection point for hints
+        #
+        # Hints must go before first path construction operator.
+        # Path operators: moveto, lineto, curveto, etc.
+        #
+        # @param operations [Array<Hash>] CharString operations
+        # @return [Integer] Index to insert hints
+        def find_injection_point(operations)
+          # Path construction operators
+          path_operators = %i[
+            rmoveto hmoveto vmoveto
+            rlineto hlineto vlineto
+            rrcurveto rcurveline rlinecurve
+            vvcurveto hhcurveto vhcurveto hvcurveto
+          ]
+
+          # Find first path operator
+          operations.each_with_index do |op, index|
+            return index if path_operators.include?(op[:name])
+          end
+
+          # No path operators found - hints go before endchar
+          operations.each_with_index do |op, index|
+            return index if op[:name] == :endchar
+          end
+
+          # Empty or malformed - inject at start
+          0
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "../../binary/base_record"
+
+module Fontisan
+  module Tables
+    class Cff
+      # CFF INDEX structure
+      #
+      # INDEX is a fundamental data structure used throughout CFF for storing
+      # arrays of variable-length data items. It's used for:
+      # - Name INDEX (font names)
+      # - String INDEX (string data)
+      # - Global Subr INDEX (global subroutines)
+      # - Local Subr INDEX (local subroutines)
+      # - CharStrings INDEX (glyph programs)
+      #
+      # Structure:
+      # - count (Card16): Number of objects stored in INDEX
+      # - offSize (OffSize): Size of offset values (1-4 bytes)
+      # - offset[count+1] (Offset): Array of offsets to data
+      # - data: The actual data bytes
+      #
+      # Offsets are relative to the byte before the data array. The first
+      # offset is always 1, not 0. 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 Reading an INDEX
+      #   index = Fontisan::Tables::Cff::Index.new(data)
+      #   puts index.count  # => 3
+      #   puts index[0]  # => first item data
+      #   index.each { |item| puts item }
+      class Index
+        # @return [Integer] Number of items in the INDEX
+        attr_reader :count
+
+        # @return [Integer] Size of offset values (1-4 bytes)
+        attr_reader :off_size
+
+        # @return [Array<Integer>] Array of offsets (count + 1 elements)
+        attr_reader :offsets
+
+        # @return [String] Binary string containing all data
+        attr_reader :data
+
+        # Initialize an INDEX from binary data
+        #
+        # @param io [IO, StringIO, String] Binary data to parse
+        # @param start_offset [Integer] Starting byte offset in the data
+        def initialize(io, start_offset: 0)
+          @io = io.is_a?(String) ? StringIO.new(io) : io
+          @start_offset = start_offset
+          @io.seek(start_offset) if @io.respond_to?(:seek)
+
+          parse!
+        end
+
+        # Get the item at the specified index
+        #
+        # @param index [Integer] Zero-based index of item to retrieve
+        # @return [String, nil] Binary data for the item, or nil if out of bounds
+        def [](index)
+          return nil if index.negative? || index >= count
+          return "" if count.zero?
+
+          # Offsets are 1-based in the data array
+          start_pos = offsets[index] - 1
+          end_pos = offsets[index + 1] - 1
+          length = end_pos - start_pos
+
+          data[start_pos, length]
+        end
+
+        # Iterate over each item in the INDEX
+        #
+        # @yield [String] Binary data for each item
+        # @return [Enumerator] If no block given
+        def each
+          return enum_for(:each) unless block_given?
+
+          count.times do |i|
+            yield self[i]
+          end
+        end
+
+        # Get all items as an array
+        #
+        # @return [Array<String>] Array of binary data strings
+        def to_a
+          Array.new(count) { |i| self[i] }
+        end
+
+        # Check if the INDEX is empty
+        #
+        # @return [Boolean] True if count is 0
+        def empty?
+          count.zero?
+        end
+
+        # Get the size of a specific item
+        #
+        # @param index [Integer] Zero-based index of item
+        # @return [Integer, nil] Size in bytes, or nil if out of bounds
+        def item_size(index)
+          return nil if index.negative? || index >= count
+          return 0 if count.zero?
+
+          offsets[index + 1] - offsets[index]
+        end
+
+        # Calculate total size of the INDEX in bytes
+        #
+        # This includes the count, offSize, offset array, and data.
+        #
+        # @return [Integer] Total size in bytes
+        def total_size
+          return 2 if count.zero? # Just the count field
+
+          # count (2) + offSize (1) + offset array + data
+          2 + 1 + ((count + 1) * off_size) + data.bytesize
+        end
+
+        private
+
+        # Parse the INDEX structure from the IO
+        def parse!
+          # Read count (Card16)
+          @count = read_uint16
+
+          # Empty INDEX has only count field
+          if @count.zero?
+            @off_size = 0
+            @offsets = []
+            @data = "".b
+            return
+          end
+
+          # Read offSize (OffSize)
+          @off_size = read_uint8
+
+          # Validate offSize
+          unless (1..4).cover?(@off_size)
+            raise CorruptedTableError,
+                  "Invalid INDEX offSize: #{@off_size} (must be 1-4)"
+          end
+
+          # Read offset array (count + 1 offsets)
+          @offsets = Array.new(@count + 1) do
+            read_offset(@off_size)
+          end
+
+          # Validate offsets
+          validate_offsets!
+
+          # Read data section
+          # Size is (last offset - 1) since offsets are 1-based
+          data_size = @offsets.last - 1
+          @data = read_bytes(data_size)
+        end
+
+        # Read an unsigned 16-bit integer
+        #
+        # @return [Integer] The value
+        def read_uint16
+          bytes = read_bytes(2)
+          bytes.unpack1("n") # Big-endian unsigned 16-bit
+        end
+
+        # Read an unsigned 8-bit integer
+        #
+        # @return [Integer] The value
+        def read_uint8
+          read_bytes(1).unpack1("C")
+        end
+
+        # Read an offset value of specified size
+        #
+        # @param size [Integer] Number of bytes (1-4)
+        # @return [Integer] The offset value
+        def read_offset(size)
+          bytes = read_bytes(size)
+
+          case size
+          when 1
+            bytes.unpack1("C")
+          when 2
+            bytes.unpack1("n")
+          when 3
+            # 24-bit big-endian
+            bytes.unpack("C3").inject(0) { |sum, byte| (sum << 8) | byte }
+          when 4
+            bytes.unpack1("N")
+          else
+            raise ArgumentError, "Invalid offset size: #{size}"
+          end
+        end
+
+        # Read specified number of bytes from IO
+        #
+        # @param count [Integer] Number of bytes to read
+        # @return [String] Binary string
+        def read_bytes(count)
+          return "".b if count.zero?
+
+          bytes = @io.read(count)
+          if bytes.nil? || bytes.bytesize < count
+            raise CorruptedTableError,
+                  "Unexpected end of INDEX data"
+          end
+
+          bytes
+        end
+
+        # Validate that offsets are in ascending order and within bounds
+        def validate_offsets!
+          # First offset must be 1
+          unless @offsets.first == 1
+            raise CorruptedTableError,
+                  "Invalid INDEX: first offset must be 1, got #{@offsets.first}"
+          end
+
+          # Check ascending order
+          @offsets.each_cons(2) do |prev, curr|
+            if curr < prev
+              raise CorruptedTableError,
+                    "Invalid INDEX: offsets are not in ascending order"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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/offset_recalculator.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Tables
+    class Cff
+      # Recalculates CFF table offsets after structure modifications
+      #
+      # When the Private DICT size changes (e.g., adding hint parameters),
+      # all offsets in the CFF table must be recalculated. This class
+      # computes new offsets based on section sizes.
+      #
+      # CFF Structure (sequential layout):
+      # - Header (fixed size)
+      # - Name INDEX
+      # - Top DICT INDEX (contains offsets to CharStrings and Private DICT)
+      # - String INDEX
+      # - Global Subr INDEX
+      # - CharStrings INDEX
+      # - Private DICT (variable size)
+      # - Local Subr INDEX (optional, within Private DICT)
+      #
+      # Key offsets to recalculate:
+      # - charstrings: Offset from CFF start to CharStrings INDEX
+      # - private: [size, offset] in Top DICT pointing to Private DICT
+      class OffsetRecalculator
+        # Calculate offsets for all CFF sections
+        #
+        # @param sections [Hash] Hash of section_name => binary_data
+        # @return [Hash] Hash of offset information
+        def self.calculate_offsets(sections)
+          offsets = {}
+          pos = 0
+
+          # Track position through CFF structure
+          pos += sections[:header].bytesize
+          pos += sections[:name_index].bytesize
+
+          # Top DICT INDEX starts here
+          offsets[:top_dict_start] = pos
+          pos += sections[:top_dict_index].bytesize
+
+          pos += sections[:string_index].bytesize
+          pos += sections[:global_subr_index].bytesize
+
+          # CharStrings INDEX offset (referenced in Top DICT)
+          offsets[:charstrings] = pos
+          pos += sections[:charstrings_index].bytesize
+
+          # Private DICT offset and size (referenced in Top DICT)
+          offsets[:private] = pos
+          offsets[:private_size] = sections[:private_dict].bytesize
+
+          offsets
+        end
+
+        # Update Top DICT with new offsets
+        #
+        # @param top_dict [Hash] Top DICT data
+        # @param offsets [Hash] Calculated offsets
+        # @return [Hash] Updated Top DICT
+        def self.update_top_dict(top_dict, offsets)
+          updated = top_dict.dup
+          updated[:charstrings] = offsets[:charstrings]
+          updated[:private] = [offsets[:private_size], offsets[:private]]
+          updated
+        end
+      end
+    end
+  end
+end