fontisan 0.1.0

data/lib/fontisan/tables/name.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require_relative "../binary/base_record"
+
+module Fontisan
+  module Tables
+    # BinData structure for a single name record
+    #
+    # Represents metadata about a string in the name table,
+    # including platform, encoding, language, and offset information.
+    class NameRecord < Binary::BaseRecord
+      uint16 :platform_id
+      uint16 :encoding_id
+      uint16 :language_id
+      uint16 :name_id
+      uint16 :string_length
+      uint16 :string_offset
+
+      # The decoded string value (set after reading from string storage)
+      attr_accessor :string
+
+      # Get the length of the string (for backward compatibility)
+      #
+      # @return [Integer] String length in bytes
+      def length
+        string_length
+      end
+
+      # Decode the string data based on platform and encoding
+      #
+      # @param data [String] Raw binary string data
+      def decode_string(data)
+        @string = case platform_id
+                  when Name::PLATFORM_MACINTOSH
+                    # Platform 1 (Mac): ASCII/MacRoman
+                    data.dup.force_encoding("ASCII-8BIT").encode("UTF-8",
+                                                                 invalid: :replace,
+                                                                 undef: :replace)
+                  when Name::PLATFORM_WINDOWS
+                    # Platform 3 (Windows): UTF-16BE
+                    data.dup.force_encoding("UTF-16BE").encode("UTF-8",
+                                                               invalid: :replace,
+                                                               undef: :replace)
+                  when Name::PLATFORM_UNICODE
+                    # Platform 0 (Unicode): UTF-16BE
+                    data.dup.force_encoding("UTF-16BE").encode("UTF-8",
+                                                               invalid: :replace,
+                                                               undef: :replace)
+                  else
+                    # Unknown platform: try UTF-8
+                    data.dup.force_encoding("UTF-8")
+                  end
+      end
+    end
+
+    # BinData structure for the 'name' (Naming Table) table
+    #
+    # The name table allows multilingual strings to be associated with the font.
+    # These strings can represent copyright notices, font names, family names,
+    # style names, and other information.
+    #
+    # Reference: OpenType specification, name table
+    #
+    # @example Reading a name table
+    #   data = File.binread("font.ttf", length, name_offset)
+    #   name = Fontisan::Tables::Name.read(data)
+    #   puts name.english_name(Fontisan::Tables::Name::FAMILY)
+    class Name < Binary::BaseRecord
+      # Name ID constants for common name records
+      COPYRIGHT = 0
+      FAMILY = 1
+      SUBFAMILY = 2
+      UNIQUE_ID = 3
+      FULL_NAME = 4
+      VERSION = 5
+      POSTSCRIPT_NAME = 6
+      TRADEMARK = 7
+      MANUFACTURER = 8
+      DESIGNER = 9
+      DESCRIPTION = 10
+      VENDOR_URL = 11
+      DESIGNER_URL = 12
+      LICENSE_DESCRIPTION = 13
+      LICENSE_URL = 14
+      PREFERRED_FAMILY = 16
+      PREFERRED_SUBFAMILY = 17
+      COMPATIBLE_FULL = 18
+      SAMPLE_TEXT = 19
+      POSTSCRIPT_CID = 20
+      WWS_FAMILY = 21
+      WWS_SUBFAMILY = 22
+
+      # Platform IDs
+      PLATFORM_UNICODE = 0
+      PLATFORM_MACINTOSH = 1
+      PLATFORM_WINDOWS = 3
+
+      # Windows language ID for US English
+      WINDOWS_LANGUAGE_EN_US = 0x0409
+
+      # Mac language ID for English
+      MAC_LANGUAGE_ENGLISH = 0
+
+      uint16 :format
+      uint16 :record_count
+      uint16 :string_offset
+      array :name_records, type: :name_record, initial_length: :record_count
+      rest :string_storage
+
+      # Hook that gets called after all fields are read
+      def after_read_hook
+        decode_all_strings
+      end
+
+      # Make sure we call our hook after BinData finishes reading
+      def do_read(io)
+        super
+        after_read_hook
+      end
+
+      # Get the count of name records (for backward compatibility)
+      #
+      # @return [Integer] Number of name records
+      def count
+        record_count
+      end
+
+      # Find an English name for the given name ID
+      #
+      # Priority: Platform 3 (Windows) with language 0x0409 (US English)
+      # Fallback: Platform 1 (Mac) with language 0
+      #
+      # @param name_id [Integer] The name ID to search for
+      # @return [String, nil] The decoded string or nil if not found
+      def english_name(name_id)
+        # First try Windows English
+        record = name_records.find do |rec|
+          rec.name_id == name_id &&
+            rec.platform_id == PLATFORM_WINDOWS &&
+            rec.language_id == WINDOWS_LANGUAGE_EN_US
+        end
+
+        # Fallback to Mac English
+        record ||= name_records.find do |rec|
+          rec.name_id == name_id &&
+            rec.platform_id == PLATFORM_MACINTOSH &&
+            rec.language_id == MAC_LANGUAGE_ENGLISH
+        end
+
+        record&.string
+      end
+
+      # Validate the table
+      #
+      # @return [Boolean] True if the table is valid
+      def valid?
+        !format.nil?
+      rescue StandardError
+        false
+      end
+
+      private
+
+      # Decode all strings from the string storage area
+      def decode_all_strings
+        # Get the raw string storage as a plain Ruby binary string
+        storage_bytes = string_storage.to_s.b
+
+        return if storage_bytes.empty?
+
+        name_records.each do |record|
+          # Extract string data from storage using offset and length
+          offset = record.string_offset
+          length = record.string_length
+
+          # Validate bounds
+          next if offset.nil? || length.nil?
+          next if offset + length > storage_bytes.bytesize
+          next if length.zero?
+
+          # Slice the bytes from storage
+          string_data = storage_bytes.byteslice(offset, length)
+          record.decode_string(string_data) if string_data && !string_data.empty?
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/tables/os2.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Tables
+    # Parser for the 'OS/2' (OS/2 and Windows Metrics) table
+    #
+    # The OS/2 table contains OS/2 and Windows-specific metrics that are
+    # required by Windows and OS/2. This includes font metrics, character
+    # ranges, vendor information, and embedding permissions.
+    #
+    # The table has evolved through multiple versions (0-5), with newer
+    # versions adding additional fields while maintaining backward
+    # compatibility.
+    #
+    # Reference: OpenType specification, OS/2 table
+    class Os2 < Binary::BaseRecord
+      endian :big
+
+      # Version 0 fields (all versions have these)
+      uint16 :version
+      int16 :x_avg_char_width
+      uint16 :us_weight_class
+      uint16 :us_width_class
+      uint16 :fs_type
+      int16 :y_subscript_x_size
+      int16 :y_subscript_y_size
+      int16 :y_subscript_x_offset
+      int16 :y_subscript_y_offset
+      int16 :y_superscript_x_size
+      int16 :y_superscript_y_size
+      int16 :y_superscript_x_offset
+      int16 :y_superscript_y_offset
+      int16 :y_strikeout_size
+      int16 :y_strikeout_position
+      int16 :s_family_class
+
+      # PANOSE - 10 bytes
+      array :panose, type: :uint8, initial_length: 10
+
+      # Unicode ranges
+      uint32 :ul_unicode_range1
+      uint32 :ul_unicode_range2
+      uint32 :ul_unicode_range3
+      uint32 :ul_unicode_range4
+
+      # Vendor ID - 4 bytes
+      string :ach_vend_id, length: 4
+
+      # Selection flags and character indices
+      uint16 :fs_selection
+      uint16 :us_first_char_index
+      uint16 :us_last_char_index
+      int16 :s_typo_ascender
+      int16 :s_typo_descender
+      int16 :s_typo_line_gap
+      uint16 :us_win_ascent
+      uint16 :us_win_descent
+
+      # Version 1+ fields
+      uint32 :ul_code_page_range1, onlyif: -> { version >= 1 }
+      uint32 :ul_code_page_range2, onlyif: -> { version >= 1 }
+
+      # Version 2+ fields
+      int16 :sx_height, onlyif: -> { version >= 2 }
+      int16 :s_cap_height, onlyif: -> { version >= 2 }
+      uint16 :us_default_char, onlyif: -> { version >= 2 }
+      uint16 :us_break_char, onlyif: -> { version >= 2 }
+      uint16 :us_max_context, onlyif: -> { version >= 2 }
+
+      # Version 5+ fields
+      uint16 :us_lower_optical_point_size, onlyif: -> { version >= 5 }
+      uint16 :us_upper_optical_point_size, onlyif: -> { version >= 5 }
+
+      # Override conditional field accessors to return nil when not present
+      # BinData's onlyif fields return default values even when not read,
+      # so we need to check the version before accessing them
+      def ul_code_page_range1
+        return nil unless version >= 1
+
+        super
+      end
+
+      def ul_code_page_range2
+        return nil unless version >= 1
+
+        super
+      end
+
+      def sx_height
+        return nil unless version >= 2
+
+        super
+      end
+
+      def s_cap_height
+        return nil unless version >= 2
+
+        super
+      end
+
+      def us_default_char
+        return nil unless version >= 2
+
+        super
+      end
+
+      def us_break_char
+        return nil unless version >= 2
+
+        super
+      end
+
+      def us_max_context
+        return nil unless version >= 2
+
+        super
+      end
+
+      def us_lower_optical_point_size
+        return nil unless version >= 5
+
+        super
+      end
+
+      def us_upper_optical_point_size
+        return nil unless version >= 5
+
+        super
+      end
+
+      # Get the vendor ID as a trimmed string
+      #
+      # @return [String] The vendor ID with trailing spaces and nulls removed
+      def vendor_id
+        return "" unless ach_vend_id
+
+        ach_vend_id.gsub(/[\x00\s]+$/, "")
+      end
+
+      # Get the embedding type flags
+      #
+      # @return [Integer] The fs_type value (embedding permissions)
+      def type_flags
+        fs_type
+      end
+
+      # Check if optical point size information is available
+      #
+      # @return [Boolean] True if version >= 5
+      def has_optical_point_size?
+        version >= 5
+      end
+
+      # Get the lower optical point size
+      #
+      # @return [Float, nil] The lower optical point size in points, or nil
+      #   if not available
+      def lower_optical_point_size
+        return nil unless has_optical_point_size?
+
+        us_lower_optical_point_size / 20.0
+      end
+
+      # Get the upper optical point size
+      #
+      # @return [Float, nil] The upper optical point size in points, or nil
+      #   if not available
+      def upper_optical_point_size
+        return nil unless has_optical_point_size?
+
+        us_upper_optical_point_size / 20.0
+      end
+    end
+  end
+end

data/lib/fontisan/tables/post.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Tables
+    # Parser for the 'post' (PostScript) table
+    #
+    # The post table contains PostScript information, primarily glyph names.
+    # Different versions exist (1.0, 2.0, 2.5, 3.0, 4.0) with varying
+    # glyph name storage strategies.
+    #
+    # Reference: OpenType specification, post table
+    class Post < Binary::BaseRecord
+      # Standard Mac glyph names for version 1.0 (258 glyphs)
+      # rubocop:disable Metrics/CollectionLiteralLength
+      STANDARD_NAMES = %w[
+        .notdef .null nonmarkingreturn space exclam quotedbl numbersign
+        dollar percent ampersand quotesingle parenleft parenright asterisk
+        plus comma hyphen period slash zero one two three four five six
+        seven eight nine colon semicolon less equal greater question at
+        A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
+        bracketleft backslash bracketright asciicircum underscore grave
+        a b c d e f g h i j k l m n o p q r s t u v w x y z
+        braceleft bar braceright asciitilde Adieresis Aring Ccedilla
+        Eacute Ntilde Odieresis Udieresis aacute agrave acircumflex
+        adieresis atilde aring ccedilla eacute egrave ecircumflex
+        edieresis iacute igrave icircumflex idieresis ntilde oacute
+        ograve ocircumflex odieresis otilde uacute ugrave ucircumflex
+        udieresis dagger degree cent sterling section bullet paragraph
+        germandbls registered copyright trademark acute dieresis notequal
+        AE Oslash infinity plusminus lessequal greaterequal yen mu
+        partialdiff summation product pi integral ordfeminine ordmasculine
+        Omega ae oslash questiondown exclamdown logicalnot radical florin
+        approxequal Delta guillemotleft guillemotright ellipsis
+        nonbreakingspace Agrave Atilde Otilde OE oe endash emdash
+        quotedblleft quotedblright quoteleft quoteright divide lozenge
+        ydieresis Ydieresis fraction currency guilsinglleft guilsinglright
+        fi fl daggerdbl periodcentered quotesinglbase quotedblbase
+        perthousand Acircumflex Ecircumflex Aacute Edieresis Egrave
+        Iacute Icircumflex Idieresis Igrave Oacute Ocircumflex apple
+        Ograve Uacute Ucircumflex Ugrave dotlessi circumflex tilde
+        macron breve dotaccent ring cedilla hungarumlaut ogonek caron
+        Lslash lslash Scaron scaron Zcaron zcaron brokenbar Eth
+        eth Yacute yacute Thorn thorn minus multiply onesuperior
+        twosuperior threesuperior onehalf onequarter threequarters franc
+        Gbreve gbreve Idotaccent Scedilla scedilla Cacute cacute Ccaron
+        ccaron dcroat
+      ].freeze
+      # rubocop:enable Metrics/CollectionLiteralLength
+
+      # Version 2.0 as Fixed 16.16 constant
+      VERSION_2_0_RAW = 131_072 # 2.0 * 65536
+
+      endian :big
+
+      int32 :version_raw
+      int32 :italic_angle_raw
+      int16 :underline_position
+      int16 :underline_thickness
+      uint32 :is_fixed_pitch
+      uint32 :min_mem_type42
+      uint32 :max_mem_type42
+      uint32 :min_mem_type1
+      uint32 :max_mem_type1
+
+      # Version 2.0 specific fields
+      uint16 :num_glyphs_v2, onlyif: -> { version_raw == VERSION_2_0_RAW }
+      rest :remaining_data
+
+      # Get version as float (Fixed 16.16 format)
+      def version
+        fixed_to_float(version_raw)
+      end
+
+      # Get italic angle as float (Fixed 16.16 format)
+      def italic_angle
+        fixed_to_float(italic_angle_raw)
+      end
+
+      # Get glyph names based on version
+      #
+      # @return [Array<String>] array of glyph names
+      def glyph_names
+        @glyph_names ||= case version
+                         when 1.0
+                           STANDARD_NAMES.dup
+                         when 2.0
+                           parse_version_2_names
+                         else
+                           []
+                         end
+      end
+
+      private
+
+      # Parse version 2.0 glyph names
+      #
+      # Version 2.0 uses a combination of standard Mac names (indices 0-257)
+      # and custom names (indices >= 258) stored as Pascal strings.
+      # rubocop:disable Metrics/PerceivedComplexity
+      def parse_version_2_names
+        return [] unless version_raw == VERSION_2_0_RAW
+        return [] if remaining_data.empty?
+
+        data = remaining_data
+        offset = 0
+
+        # Read glyph name indices (uint16 array)
+        indices = []
+        num_glyphs_v2.times do
+          break if offset + 2 > data.length
+
+          index = data[offset, 2].unpack1("n")
+          indices << index
+          offset += 2
+        end
+
+        # Read Pascal strings for custom names (index >= 258)
+        custom_names = []
+        while offset < data.length
+          length = data[offset].ord
+          offset += 1
+          break if length.zero? || offset + length > data.length
+
+          name = data[offset, length]
+          offset += length
+          custom_names << name
+        end
+
+        # Map indices to names
+        indices.map do |index|
+          if index < 258
+            # Standard Mac name
+            STANDARD_NAMES[index]
+          else
+            # Custom name
+            custom_index = index - 258
+            if custom_index < custom_names.length
+              custom_names[custom_index]
+            else
+              ".notdef"
+            end
+          end
+        end
+      end
+      # rubocop:enable Metrics/PerceivedComplexity
+    end
+  end
+end

data/lib/fontisan/true_type_collection.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "bindata"
+require_relative "constants"
+
+module Fontisan
+  # TrueType Collection domain object using BinData
+  #
+  # Represents a complete TrueType Collection file using BinData's declarative
+  # DSL for binary structure definition. The structure definition IS the
+  # documentation, and BinData handles all low-level reading/writing.
+  #
+  # @example Reading and extracting fonts
+  #   File.open("Helvetica.ttc", "rb") do |io|
+  #     ttc = TrueTypeCollection.read(io)
+  #     puts ttc.num_fonts  # => 6
+  #     fonts = ttc.extract_fonts(io)  # => [TrueTypeFont, TrueTypeFont, ...]
+  #   end
+  class TrueTypeCollection < BinData::Record
+    endian :big
+
+    string :tag, length: 4, assert: "ttcf"
+    uint16 :major_version
+    uint16 :minor_version
+    uint32 :num_fonts
+    array :font_offsets, type: :uint32, initial_length: :num_fonts
+
+    # Read TrueType Collection from a file
+    #
+    # @param path [String] Path to the TTC file
+    # @return [TrueTypeCollection] A new instance
+    # @raise [ArgumentError] if path is nil or empty
+    # @raise [Errno::ENOENT] if file does not exist
+    # @raise [RuntimeError] if file format is invalid
+    def self.from_file(path)
+      if path.nil? || path.to_s.empty?
+        raise ArgumentError,
+              "path cannot be nil or empty"
+      end
+      raise Errno::ENOENT, "File not found: #{path}" unless File.exist?(path)
+
+      File.open(path, "rb") { |io| read(io) }
+    rescue BinData::ValidityError => e
+      raise "Invalid TTC file: #{e.message}"
+    rescue EOFError => e
+      raise "Invalid TTC file: unexpected end of file - #{e.message}"
+    end
+
+    # Extract fonts as TrueTypeFont objects
+    #
+    # Reads each font from the TTC file and returns them as TrueTypeFont objects.
+    #
+    # @param io [IO] Open file handle to read fonts from
+    # @return [Array<TrueTypeFont>] Array of font objects
+    def extract_fonts(io)
+      require_relative "true_type_font"
+
+      font_offsets.map do |offset|
+        TrueTypeFont.from_ttc(io, offset)
+      end
+    end
+
+    # Get a single font from the collection (Fontisan extension)
+    #
+    # @param index [Integer] Index of the font (0-based)
+    # @param io [IO] Open file handle
+    # @return [TrueTypeFont, nil] Font object or nil if index out of range
+    def font(index, io)
+      return nil if index >= num_fonts
+
+      require_relative "true_type_font"
+      TrueTypeFont.from_ttc(io, font_offsets[index])
+    end
+
+    # Get font count (Fontisan extension)
+    #
+    # @return [Integer] Number of fonts in collection
+    def font_count
+      num_fonts
+    end
+
+    # Validate format correctness
+    #
+    # @return [Boolean] true if the format is valid, false otherwise
+    def valid?
+      tag == Constants::TTC_TAG && num_fonts.positive? && font_offsets.length == num_fonts
+    rescue StandardError
+      false
+    end
+
+    # Get the TTC version as a single integer
+    #
+    #  @return [Integer] Version number (e.g., 0x00010000 for version 1.0)
+    def version
+      (major_version << 16) | minor_version
+    end
+  end
+end