harfbuzz-ruby 1.0.0

data/lib/harfbuzz/face.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module HarfBuzz
+  # Wraps hb_face_t — a font face (font file + index)
+  class Face
+    attr_reader :ptr
+
+    # Creates a Face from a Blob and face index
+    # @param blob [Blob] Font data blob
+    # @param index [Integer] Face index within the blob (0 for single-face fonts)
+    def initialize(blob, index = 0)
+      @blob = blob
+      @ptr = C.hb_face_create(blob.ptr, index)
+      raise AllocationError, "Failed to create face" if @ptr.null?
+
+      register_finalizer
+    end
+
+    # Creates a Face with custom table access (callback-based)
+    # @yield [tag] Called with the hb_tag_t for each table requested
+    # @yieldreturn [Blob] Table blob
+    # @return [Face]
+    def self.for_tables(&block)
+      callback_holder = []
+      cb = FFI::Function.new(:pointer, [:pointer, :uint32, :pointer]) do |_face, tag, _user_data|
+        blob = block.call(tag)
+        blob ? blob.ptr : C.hb_blob_get_empty
+      end
+      callback_holder << cb
+
+      ptr = C.hb_face_create_for_tables(cb, nil, nil)
+      obj = allocate
+      obj.instance_variable_set(:@ptr, ptr)
+      obj.instance_variable_set(:@callback_holder, callback_holder)
+      obj.send(:register_finalizer)
+      obj
+    end
+
+    # Returns the singleton empty face
+    # @return [Face]
+    def self.empty
+      wrap_borrowed(C.hb_face_get_empty)
+    end
+
+    # Returns the number of faces in a blob
+    # @param blob [Blob] Font blob
+    # @return [Integer] Face count
+    def self.count(blob)
+      C.hb_face_count(blob.ptr)
+    end
+
+    # @return [Integer] Face index
+    def index
+      C.hb_face_get_index(@ptr)
+    end
+
+    # @param idx [Integer] Face index
+    def index=(idx)
+      C.hb_face_set_index(@ptr, idx)
+    end
+
+    # @return [Integer] Units per em
+    def upem
+      C.hb_face_get_upem(@ptr)
+    end
+
+    # @param u [Integer] Units per em
+    def upem=(u)
+      C.hb_face_set_upem(@ptr, u)
+    end
+
+    # @return [Integer] Number of glyphs in this face
+    def glyph_count
+      C.hb_face_get_glyph_count(@ptr)
+    end
+
+    # @param count [Integer] Glyph count override
+    def glyph_count=(count)
+      C.hb_face_set_glyph_count(@ptr, count)
+    end
+
+    # @return [Array<Integer>] Array of table tags
+    def table_tags
+      # First call: pass count=0 to get total number of tables (return value)
+      count_ptr = FFI::MemoryPointer.new(:uint)
+      count_ptr.write_uint(0)
+      total = C.hb_face_get_table_tags(@ptr, 0, count_ptr, nil)
+      return [] if total.zero?
+
+      tags_ptr = FFI::MemoryPointer.new(:uint32, total)
+      count_ptr.write_uint(total)
+      C.hb_face_get_table_tags(@ptr, 0, count_ptr, tags_ptr)
+      actual = count_ptr.read_uint
+      tags_ptr.read_array_of_uint32(actual)
+    end
+
+    # Returns the blob for a specific table
+    # @param tag [Integer] OpenType table tag
+    # @return [Blob] Table blob (owned)
+    def table(tag)
+      ptr = C.hb_face_reference_table(@ptr, tag)
+      Blob.wrap_owned(ptr)
+    end
+
+    alias reference_table table
+
+    # Returns the blob for the entire font face
+    # @return [Blob] Face blob (owned)
+    def blob
+      ptr = C.hb_face_reference_blob(@ptr)
+      Blob.wrap_owned(ptr)
+    end
+
+    # @return [Set] Set of all Unicode codepoints in this face
+    def unicodes
+      set = Set.new
+      C.hb_face_collect_unicodes(@ptr, set.ptr)
+      set
+    end
+
+    # @return [Map] Map from Unicode codepoints to nominal glyph IDs
+    def nominal_glyph_mapping
+      map = Map.new
+      C.hb_face_collect_nominal_glyph_mapping(@ptr, map.ptr, FFI::Pointer::NULL)
+      map
+    end
+
+    # @return [Set] Set of variation selector codepoints
+    def variation_selectors
+      set = Set.new
+      C.hb_face_collect_variation_selectors(@ptr, set.ptr)
+      set
+    end
+
+    # @param selector [Integer] Variation selector codepoint
+    # @return [Set] Set of Unicode codepoints supported via the variation selector
+    def variation_unicodes(selector)
+      set = Set.new
+      C.hb_face_collect_variation_unicodes(@ptr, selector, set.ptr)
+      set
+    end
+
+    # @return [Boolean] true if face is immutable
+    def immutable?
+      C.from_hb_bool(C.hb_face_is_immutable(@ptr))
+    end
+
+    # Makes the face immutable (thread-safe to share after this)
+    # @return [self]
+    def make_immutable!
+      C.hb_face_make_immutable(@ptr)
+      self
+    end
+
+    def inspect
+      "#<HarfBuzz::Face index=#{index} upem=#{upem} glyph_count=#{glyph_count}>"
+    end
+
+    def self.wrap_owned(ptr)
+      obj = allocate
+      obj.instance_variable_set(:@ptr, ptr)
+      obj.send(:register_finalizer)
+      obj
+    end
+
+    def self.wrap_borrowed(ptr)
+      obj = allocate
+      obj.instance_variable_set(:@ptr, ptr)
+      obj.instance_variable_set(:@borrowed, true)
+      obj
+    end
+
+    private
+
+    def register_finalizer
+      return if instance_variable_defined?(:@borrowed) && @borrowed
+
+      HarfBuzz::Face.define_finalizer(self, @ptr)
+    end
+
+    def self.define_finalizer(obj, ptr)
+      destroy = C.method(:hb_face_destroy)
+      ObjectSpace.define_finalizer(obj, proc { destroy.call(ptr) })
+    end
+  end
+end

data/lib/harfbuzz/feature.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module HarfBuzz
+  # Represents an OpenType feature (e.g., "liga", "+kern", "smcp=1")
+  class Feature
+    HB_FEATURE_GLOBAL_START = 0
+    HB_FEATURE_GLOBAL_END   = 0xFFFFFFFF
+
+    def initialize(struct)
+      @struct = struct
+    end
+
+    # @return [Integer] Feature tag as uint32
+    def tag
+      @struct[:tag]
+    end
+
+    # @return [Integer] Feature value
+    def value
+      @struct[:value]
+    end
+
+    # @return [Integer] Start index in buffer (HB_FEATURE_GLOBAL_START for global)
+    def start
+      @struct[:start]
+    end
+
+    # @return [Integer] End index in buffer (HB_FEATURE_GLOBAL_END for global)
+    def end_index
+      @struct[:end]
+    end
+
+    # Parses a feature string such as "liga", "+kern", "-calt", "smcp=1"
+    # @param str [String] Feature string
+    # @return [Feature] Parsed feature
+    # @raise [FeatureParseError] If the string cannot be parsed
+    def self.from_string(str)
+      struct = C::HbFeatureT.new
+      result = C.hb_feature_from_string(str, str.bytesize, struct)
+      raise FeatureParseError, "Invalid feature string: #{str.inspect}" if result.zero?
+
+      new(struct)
+    end
+
+    # Builds a list of Feature objects from a Hash
+    # @param hash [Hash] Map of tag => value (true/false/Integer)
+    # @return [Array<Feature>] List of features
+    def self.from_hash(hash)
+      hash.map do |tag, value|
+        case value
+        when true    then from_string("+#{tag}")
+        when false   then from_string("-#{tag}")
+        when Integer then from_string("#{tag}=#{value}")
+        else raise InvalidArgumentError, "Unknown feature value: #{value.inspect}"
+        end
+      end
+    end
+
+    # Returns the FFI struct for passing to C functions
+    # @return [C::HbFeatureT]
+    def to_struct
+      @struct
+    end
+
+    # @return [String] Feature string representation
+    def to_s
+      buf = FFI::MemoryPointer.new(:char, 128)
+      C.hb_feature_to_string(@struct, buf, 128)
+      buf.read_string
+    end
+
+    def inspect
+      "#<HarfBuzz::Feature #{to_s}>"
+    end
+  end
+end

data/lib/harfbuzz/flags.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module HarfBuzz
+  # Utility module for converting between symbol arrays and bitwise flag integers
+  #
+  # @example Buffer flags
+  #   flags = HarfBuzz::Flags.to_int(:buffer_flags, [:bot, :eot])
+  #   buffer.flags = flags
+  #
+  # @example Subset flags
+  #   flags = HarfBuzz::Flags.to_int(:subset_flags, [:no_hinting, :retain_gids])
+  #   input.flags = flags
+  module Flags
+    # Maps flag set names to their symbol→integer mappings
+    MAPPINGS = {
+      buffer_flags: {
+        default:                           C::BUFFER_FLAG_DEFAULT,
+        bot:                               C::BUFFER_FLAG_BOT,
+        eot:                               C::BUFFER_FLAG_EOT,
+        preserve_default_ignorables:       C::BUFFER_FLAG_PRESERVE_DEFAULT_IGNORABLES,
+        remove_default_ignorables:         C::BUFFER_FLAG_REMOVE_DEFAULT_IGNORABLES,
+        do_not_insert_dotted_circle:       C::BUFFER_FLAG_DO_NOT_INSERT_DOTTED_CIRCLE,
+        verify:                            C::BUFFER_FLAG_VERIFY,
+        produce_unsafe_to_concat:          C::BUFFER_FLAG_PRODUCE_UNSAFE_TO_CONCAT,
+        produce_safe_to_insert_tatweel:    C::BUFFER_FLAG_PRODUCE_SAFE_TO_INSERT_TATWEEL
+      }.freeze,
+      glyph_flags: {
+        unsafe_to_break:                   C::GLYPH_FLAG_UNSAFE_TO_BREAK,
+        unsafe_to_concat:                  C::GLYPH_FLAG_UNSAFE_TO_CONCAT,
+        safe_to_insert_tatweel:            C::GLYPH_FLAG_SAFE_TO_INSERT_TATWEEL,
+        defined:                           C::GLYPH_FLAG_DEFINED
+      }.freeze,
+      ot_var_axis_flags: {
+        hidden:                            C::OT_VAR_AXIS_FLAG_HIDDEN
+      }.freeze,
+      subset_flags: {
+        default:                           C::SUBSET_FLAGS_DEFAULT,
+        no_hinting:                        C::SUBSET_FLAGS_NO_HINTING,
+        retain_gids:                       C::SUBSET_FLAGS_RETAIN_GIDS,
+        desubroutinize:                    C::SUBSET_FLAGS_DESUBROUTINIZE,
+        name_legacy:                       C::SUBSET_FLAGS_NAME_LEGACY,
+        set_overlaps_flag:                 C::SUBSET_FLAGS_SET_OVERLAPS_FLAG,
+        passthrough_unrecognized:          C::SUBSET_FLAGS_PASSTHROUGH_UNRECOGNIZED,
+        notdef_outline:                    C::SUBSET_FLAGS_NOTDEF_OUTLINE,
+        glyph_names:                       C::SUBSET_FLAGS_GLYPH_NAMES,
+        no_prune_unicode_ranges:           C::SUBSET_FLAGS_NO_PRUNE_UNICODE_RANGES,
+        optimize_iup_deltas:               C::SUBSET_FLAGS_OPTIMIZE_IUP_DELTAS
+      }.freeze
+    }.freeze
+
+    # Converts an array of symbols to a bitwise flag integer
+    # @param mapping_name [Symbol] Name of the flag mapping (e.g., :buffer_flags)
+    # @param symbols [Array<Symbol>] Flag symbols to combine
+    # @return [Integer] Combined bitmask
+    # @raise [ArgumentError] If mapping_name or a symbol is unknown
+    def self.to_int(mapping_name, symbols)
+      mapping = MAPPINGS.fetch(mapping_name) do
+        raise ArgumentError, "Unknown flag mapping: #{mapping_name.inspect}. " \
+                             "Available: #{MAPPINGS.keys.inspect}"
+      end
+
+      Array(symbols).inject(0) do |acc, sym|
+        bit = mapping.fetch(sym) do
+          raise ArgumentError, "Unknown flag #{sym.inspect} in #{mapping_name}. " \
+                               "Available: #{mapping.keys.inspect}"
+        end
+        acc | bit
+      end
+    end
+
+    # Converts a bitwise flag integer to an array of symbols
+    # @param mapping_name [Symbol] Name of the flag mapping
+    # @param int_value [Integer] Bitmask to decode
+    # @return [Array<Symbol>] Symbols whose bits are set
+    # @raise [ArgumentError] If mapping_name is unknown
+    def self.to_symbols(mapping_name, int_value)
+      mapping = MAPPINGS.fetch(mapping_name) do
+        raise ArgumentError, "Unknown flag mapping: #{mapping_name.inspect}. " \
+                             "Available: #{MAPPINGS.keys.inspect}"
+      end
+
+      mapping.filter_map { |sym, bit| sym if bit != 0 && (int_value & bit) == bit }
+    end
+  end
+end