harfbuzz-ruby 1.0.0

data/lib/harfbuzz/unicode_funcs.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module HarfBuzz
+  # Wraps hb_unicode_funcs_t — Unicode property callbacks
+  class UnicodeFuncs
+    attr_reader :ptr
+
+    # Creates a new UnicodeFuncs, optionally inheriting from a parent
+    # @param parent [UnicodeFuncs, nil] Parent funcs (nil = use default)
+    def initialize(parent = nil)
+      parent_ptr = parent ? parent.ptr : C.hb_unicode_funcs_get_default
+      @ptr = C.hb_unicode_funcs_create(parent_ptr)
+      raise AllocationError, "Failed to create unicode_funcs" if @ptr.null?
+
+      HarfBuzz::UnicodeFuncs.define_finalizer(self, @ptr)
+    end
+
+    # Returns the default Unicode functions
+    # @return [UnicodeFuncs]
+    def self.default
+      wrap_borrowed(C.hb_unicode_funcs_get_default)
+    end
+
+    # Returns the empty Unicode functions
+    # @return [UnicodeFuncs]
+    def self.empty
+      wrap_borrowed(C.hb_unicode_funcs_get_empty)
+    end
+
+    # Returns the parent functions
+    # @return [UnicodeFuncs]
+    def parent
+      self.class.wrap_borrowed(C.hb_unicode_funcs_get_parent(@ptr))
+    end
+
+    # @return [Boolean] true if immutable
+    def immutable?
+      C.from_hb_bool(C.hb_unicode_funcs_is_immutable(@ptr))
+    end
+
+    # Makes immutable
+    # @return [self]
+    def make_immutable!
+      C.hb_unicode_funcs_make_immutable(@ptr)
+      self
+    end
+
+    # Sets a custom general_category function
+    # @yield [codepoint] Returns general category symbol
+    def on_general_category(&block)
+      @general_category_callback = block
+      cb = FFI::Function.new(:int, [:pointer, :uint32, :pointer]) do |_ufuncs, cp, _user_data|
+        result = block.call(cp)
+        C::UnicodeGeneralCategory[result] || result
+      end
+      @general_category_ffi = cb
+      C.hb_unicode_funcs_set_general_category_func(@ptr, cb, nil, nil)
+    end
+
+    # Sets a custom combining_class function
+    # @yield [codepoint] Returns combining class integer
+    def on_combining_class(&block)
+      @combining_class_callback = block
+      cb = FFI::Function.new(:uint, [:pointer, :uint32, :pointer]) do |_ufuncs, cp, _user_data|
+        block.call(cp)
+      end
+      @combining_class_ffi = cb
+      C.hb_unicode_funcs_set_combining_class_func(@ptr, cb, nil, nil)
+    end
+
+    # Sets a custom mirroring function
+    # @yield [codepoint] Returns mirrored codepoint
+    def on_mirroring(&block)
+      @mirroring_callback = block
+      cb = FFI::Function.new(:uint32, [:pointer, :uint32, :pointer]) do |_ufuncs, cp, _user_data|
+        block.call(cp)
+      end
+      @mirroring_ffi = cb
+      C.hb_unicode_funcs_set_mirroring_func(@ptr, cb, nil, nil)
+    end
+
+    # Sets a custom script function
+    # @yield [codepoint] Returns script value
+    def on_script(&block)
+      @script_callback = block
+      cb = FFI::Function.new(:uint32, [:pointer, :uint32, :pointer]) do |_ufuncs, cp, _user_data|
+        block.call(cp)
+      end
+      @script_ffi = cb
+      C.hb_unicode_funcs_set_script_func(@ptr, cb, nil, nil)
+    end
+
+    # Sets a custom compose function
+    # @yield [a, b] Returns composed codepoint or nil
+    def on_compose(&block)
+      @compose_callback = block
+      cb = FFI::Function.new(:int, [:pointer, :uint32, :uint32, :pointer, :pointer]) do
+        |_ufuncs, a, b, ab_ptr, _user_data|
+        result = block.call(a, b)
+        if result
+          ab_ptr.write_uint32(result)
+          1
+        else
+          0
+        end
+      end
+      @compose_ffi = cb
+      C.hb_unicode_funcs_set_compose_func(@ptr, cb, nil, nil)
+    end
+
+    # Sets a custom decompose function
+    # @yield [ab] Returns [a, b] array or nil
+    def on_decompose(&block)
+      @decompose_callback = block
+      cb = FFI::Function.new(:int, [:pointer, :uint32, :pointer, :pointer, :pointer]) do
+        |_ufuncs, ab, a_ptr, b_ptr, _user_data|
+        result = block.call(ab)
+        if result
+          a_ptr.write_uint32(result[0])
+          b_ptr.write_uint32(result[1])
+          1
+        else
+          0
+        end
+      end
+      @decompose_ffi = cb
+      C.hb_unicode_funcs_set_decompose_func(@ptr, cb, nil, nil)
+    end
+
+    # Queries the general category of a codepoint
+    # @param cp [Integer] Unicode codepoint
+    # @return [Symbol] General category
+    def general_category(cp)
+      C.hb_unicode_general_category(@ptr, cp)
+    end
+
+    # Queries the combining class of a codepoint
+    # @param cp [Integer] Unicode codepoint
+    # @return [Integer] Combining class
+    def combining_class(cp)
+      C.hb_unicode_combining_class(@ptr, cp)
+    end
+
+    # Queries the mirror codepoint
+    # @param cp [Integer] Unicode codepoint
+    # @return [Integer] Mirrored codepoint (or same if no mirror)
+    def mirroring(cp)
+      C.hb_unicode_mirroring(@ptr, cp)
+    end
+
+    # Queries the script of a codepoint
+    # @param cp [Integer] Unicode codepoint
+    # @return [Integer] Script value
+    def script(cp)
+      C.hb_unicode_script(@ptr, cp)
+    end
+
+    # Composes two codepoints into one
+    # @param a [Integer] First codepoint
+    # @param b [Integer] Second codepoint
+    # @return [Integer, nil] Composed codepoint or nil
+    def compose(a, b)
+      ab_ptr = FFI::MemoryPointer.new(:uint32)
+      ok = C.hb_unicode_compose(@ptr, a, b, ab_ptr)
+      ok.zero? ? nil : ab_ptr.read_uint32
+    end
+
+    # Decomposes a codepoint into two
+    # @param cp [Integer] Codepoint to decompose
+    # @return [Array<Integer>, nil] [a, b] or nil
+    def decompose(cp)
+      a_ptr = FFI::MemoryPointer.new(:uint32)
+      b_ptr = FFI::MemoryPointer.new(:uint32)
+      ok = C.hb_unicode_decompose(@ptr, cp, a_ptr, b_ptr)
+      ok.zero? ? nil : [a_ptr.read_uint32, b_ptr.read_uint32]
+    end
+
+    def inspect
+      "#<HarfBuzz::UnicodeFuncs immutable=#{immutable?}>"
+    end
+
+    def self.wrap_owned(ptr)
+      obj = allocate
+      obj.instance_variable_set(:@ptr, ptr)
+      define_finalizer(obj, ptr)
+      obj
+    end
+
+    def self.wrap_borrowed(ptr)
+      obj = allocate
+      obj.instance_variable_set(:@ptr, ptr)
+      obj.instance_variable_set(:@borrowed, true)
+      obj
+    end
+
+    def self.define_finalizer(obj, ptr)
+      destroy = C.method(:hb_unicode_funcs_destroy)
+      ObjectSpace.define_finalizer(obj, proc { destroy.call(ptr) })
+    end
+  end
+end

data/lib/harfbuzz/variation.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module HarfBuzz
+  # Represents an OpenType variation axis value (e.g., "wght=700")
+  class Variation
+    def initialize(struct)
+      @struct = struct
+    end
+
+    # @return [Integer] Variation axis tag as uint32
+    def tag
+      @struct[:tag]
+    end
+
+    # @return [Float] Variation axis value
+    def value
+      @struct[:value]
+    end
+
+    # Parses a variation string such as "wght=700" or "ital=1"
+    # @param str [String] Variation string
+    # @return [Variation] Parsed variation
+    # @raise [VariationParseError] If the string cannot be parsed
+    def self.from_string(str)
+      struct = C::HbVariationT.new
+      result = C.hb_variation_from_string(str, str.bytesize, struct)
+      raise VariationParseError, "Invalid variation string: #{str.inspect}" if result.zero?
+
+      new(struct)
+    end
+
+    # Returns the FFI struct for passing to C functions
+    # @return [C::HbVariationT]
+    def to_struct
+      @struct
+    end
+
+    # @return [String] Variation string representation
+    def to_s
+      buf = FFI::MemoryPointer.new(:char, 64)
+      C.hb_variation_to_string(@struct, buf, 64)
+      buf.read_string
+    end
+
+    def inspect
+      "#<HarfBuzz::Variation #{to_s}>"
+    end
+  end
+end

data/lib/harfbuzz/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HarfBuzz
+  VERSION = "1.0.0"
+end

data/lib/harfbuzz-ffi.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Compatibility alias: require "harfbuzz-ffi" is equivalent to require "harfbuzz"
+require_relative "harfbuzz"

data/lib/harfbuzz.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require_relative "harfbuzz/version"
+require_relative "harfbuzz/error"
+require_relative "harfbuzz/library"
+
+# Load FFI low-level layer
+require_relative "harfbuzz/c/base"
+require_relative "harfbuzz/c/enums"
+require_relative "harfbuzz/c/structs"
+require_relative "harfbuzz/c/version"
+require_relative "harfbuzz/c/common"
+require_relative "harfbuzz/c/blob"
+require_relative "harfbuzz/c/buffer"
+require_relative "harfbuzz/c/face"
+require_relative "harfbuzz/c/font"
+require_relative "harfbuzz/c/font_funcs"
+require_relative "harfbuzz/c/shape"
+require_relative "harfbuzz/c/map"
+require_relative "harfbuzz/c/set"
+require_relative "harfbuzz/c/shape_plan"
+require_relative "harfbuzz/c/unicode"
+require_relative "harfbuzz/c/draw"
+require_relative "harfbuzz/c/paint"
+require_relative "harfbuzz/c/ot/layout"
+require_relative "harfbuzz/c/ot/var"
+require_relative "harfbuzz/c/ot/color"
+require_relative "harfbuzz/c/ot/math"
+require_relative "harfbuzz/c/ot/meta"
+require_relative "harfbuzz/c/ot/metrics"
+require_relative "harfbuzz/c/ot/name"
+require_relative "harfbuzz/c/ot/shape"
+require_relative "harfbuzz/c/ot/font"
+require_relative "harfbuzz/c/aat/layout"
+
+# Load high-level Ruby layer
+require_relative "harfbuzz/glyph_info"
+require_relative "harfbuzz/glyph_position"
+require_relative "harfbuzz/feature"
+require_relative "harfbuzz/variation"
+require_relative "harfbuzz/blob"
+require_relative "harfbuzz/buffer"
+require_relative "harfbuzz/face"
+require_relative "harfbuzz/font"
+require_relative "harfbuzz/font_funcs"
+require_relative "harfbuzz/flags"
+require_relative "harfbuzz/map"
+require_relative "harfbuzz/set"
+require_relative "harfbuzz/shape_plan"
+require_relative "harfbuzz/unicode_funcs"
+require_relative "harfbuzz/draw_funcs"
+require_relative "harfbuzz/paint_funcs"
+require_relative "harfbuzz/shaping_result"
+
+# OT namespace
+module HarfBuzz
+  module OT; end
+end
+require_relative "harfbuzz/ot/layout"
+require_relative "harfbuzz/ot/var"
+require_relative "harfbuzz/ot/color"
+require_relative "harfbuzz/ot/math"
+require_relative "harfbuzz/ot/meta"
+require_relative "harfbuzz/ot/metrics"
+require_relative "harfbuzz/ot/name"
+require_relative "harfbuzz/ot/shape"
+require_relative "harfbuzz/ot/font"
+
+# AAT namespace
+module HarfBuzz
+  module AAT; end
+end
+require_relative "harfbuzz/aat/layout"
+
+# Subset (loads libharfbuzz-subset if available)
+require_relative "harfbuzz/c/subset"
+require_relative "harfbuzz/subset"
+
+# HarfBuzz Ruby FFI Bindings
+#
+# This module provides complete Ruby bindings for the HarfBuzz text shaping engine.
+# It uses FFI to provide both low-level C API access (HarfBuzz::C) and high-level
+# Ruby-friendly interfaces.
+#
+# @example Basic shaping
+#   blob = HarfBuzz::Blob.from_file!("font.ttf")
+#   face = HarfBuzz::Face.new(blob, 0)
+#   font = HarfBuzz::Font.new(face)
+#   buffer = HarfBuzz::Buffer.new
+#   buffer.add_utf8("Hello")
+#   buffer.guess_segment_properties
+#   HarfBuzz.shape(font, buffer)
+module HarfBuzz
+  # Returns the HarfBuzz library version as an array [major, minor, micro]
+  # @return [Array<Integer>] Version array
+  def self.version
+    major_ptr = FFI::MemoryPointer.new(:uint)
+    minor_ptr = FFI::MemoryPointer.new(:uint)
+    micro_ptr = FFI::MemoryPointer.new(:uint)
+
+    C.hb_version(major_ptr, minor_ptr, micro_ptr)
+
+    [major_ptr.read_uint, minor_ptr.read_uint, micro_ptr.read_uint]
+  end
+
+  # Returns the HarfBuzz library version as a string
+  # @return [String] Version string (e.g., "8.3.0")
+  def self.version_string
+    C.hb_version_string
+  end
+
+  # Checks if the library version is at least the specified version
+  # @param major [Integer] Major version
+  # @param minor [Integer] Minor version
+  # @param micro [Integer] Micro version
+  # @return [Boolean] true if version >= specified
+  def self.version_atleast?(major, minor, micro)
+    C.from_hb_bool(C.hb_version_atleast(major, minor, micro))
+  end
+
+  class << self
+    alias version_at_least? version_atleast?
+  end
+
+  # Converts a 4-character string, Symbol, or Integer to an OpenType tag (uint32)
+  # @param str [String, Symbol, Integer] Tag as string (e.g., "GSUB"), symbol, or uint32 integer
+  # @return [Integer] Tag as uint32
+  def self.tag(str)
+    case str
+    when Integer then str
+    when Symbol  then tag(str.to_s)
+    when String  then C.hb_tag_from_string(str, str.bytesize)
+    else raise InvalidArgumentError, "Cannot convert #{str.class} to tag"
+    end
+  end
+
+  # Converts an OpenType tag (uint32) to a 4-character string
+  # @param tag [Integer] Tag as uint32
+  # @return [String] 4-character tag string
+  def self.tag_to_s(tag)
+    buf = FFI::MemoryPointer.new(:char, 4)
+    C.hb_tag_to_string(tag, buf)
+    buf.read_bytes(4)
+  end
+
+  # Converts a direction string to a direction enum value
+  # @param str [String] Direction string (e.g., "ltr")
+  # @return [Symbol] Direction symbol
+  def self.direction(str)
+    C.hb_direction_from_string(str, str.bytesize)
+  end
+
+  # Returns a language opaque pointer from a BCP 47 language tag string
+  # @param str [String] BCP 47 language tag (e.g., "en", "ar")
+  # @return [FFI::Pointer] Language pointer
+  def self.language(str)
+    C.hb_language_from_string(str, str.bytesize)
+  end
+
+  # Returns the default language
+  # @return [FFI::Pointer] Default language pointer
+  def self.default_language
+    C.hb_language_get_default
+  end
+
+  # Returns the BCP 47 string representation of a language pointer
+  # @param lang [FFI::Pointer] Language pointer (from HarfBuzz.language)
+  # @return [String] BCP 47 language tag string
+  def self.language_to_s(lang)
+    C.hb_language_to_string(lang)
+  end
+
+  # Checks if two language tags match (BCP 47 prefix comparison)
+  # @param lang1 [FFI::Pointer] First language pointer
+  # @param lang2 [FFI::Pointer] Second language pointer
+  # @return [Boolean] true if languages match
+  def self.language_matches?(lang1, lang2)
+    C.from_hb_bool(C.hb_language_matches(lang1, lang2))
+  end
+
+  # Converts a script name string to a script value
+  # @param str [String] Script name (e.g., "Arab", "Latn")
+  # @return [Integer] Script value
+  def self.script(str)
+    C.hb_script_from_string(str, str.bytesize)
+  end
+
+  # Converts an ISO 15924 OpenType tag to a script value
+  # @param tag [Integer] ISO 15924 tag (e.g., HarfBuzz.tag("Arab"))
+  # @return [Integer] Script value
+  def self.script_from_tag(tag)
+    C.hb_script_from_iso15924_tag(tag)
+  end
+
+  # Extracts the alpha component from an RGBA color value
+  # @param color [Integer] RGBA color as uint32
+  # @return [Integer] Alpha (0-255)
+  def self.color_alpha(color)
+    C.hb_color_get_alpha(color)
+  end
+
+  # Extracts the red component from an RGBA color value
+  # @param color [Integer] RGBA color as uint32
+  # @return [Integer] Red (0-255)
+  def self.color_red(color)
+    C.hb_color_get_red(color)
+  end
+
+  # Extracts the green component from an RGBA color value
+  # @param color [Integer] RGBA color as uint32
+  # @return [Integer] Green (0-255)
+  def self.color_green(color)
+    C.hb_color_get_green(color)
+  end
+
+  # Extracts the blue component from an RGBA color value
+  # @param color [Integer] RGBA color as uint32
+  # @return [Integer] Blue (0-255)
+  def self.color_blue(color)
+    C.hb_color_get_blue(color)
+  end
+
+  # Returns the horizontal direction for a script
+  # @param script [Integer] Script value
+  # @return [Symbol] Direction symbol (:ltr or :rtl)
+  def self.script_horizontal_direction(script)
+    C.hb_script_get_horizontal_direction(script)
+  end
+
+  # Shapes text in the buffer using the font
+  # @param font [Font] Font to use for shaping
+  # @param buffer [Buffer] Buffer containing text to shape
+  # @param features [Array<Feature>] Optional features to apply
+  # @param shapers [Array<String>, nil] Optional list of shapers to try
+  def self.shape(font, buffer, features = [], shapers: nil)
+    features_ptr = build_features_ptr(features)
+
+    if shapers
+      shapers_ptrs = shapers.map { |s| FFI::MemoryPointer.from_string(s) }
+      shapers_ptrs << FFI::Pointer::NULL
+      shapers_ptr = FFI::MemoryPointer.new(:pointer, shapers_ptrs.size)
+      shapers_ptrs.each_with_index { |p, i| shapers_ptr[i].put_pointer(0, p) }
+      C.hb_shape_full(font.ptr, buffer.ptr, features_ptr, features.size, shapers_ptr)
+    else
+      C.hb_shape(font.ptr, buffer.ptr, features_ptr, features.size)
+    end
+  end
+
+  # Returns the list of available shapers
+  # @return [Array<String>] List of shaper names
+  def self.shapers
+    ptr = C.hb_shape_list_shapers
+    result = []
+    i = 0
+    loop do
+      p = ptr.get_pointer(i * FFI::Pointer.size)
+      break if p.null?
+
+      result << p.read_string
+      i += 1
+    end
+    result
+  end
+
+  # High-level shaping convenience method
+  #
+  # @param text [String] Text to shape
+  # @param font_path [String] Path to font file
+  # @param features [Array<Feature, String>, Hash] Features to apply
+  # @param direction [Symbol, nil] Text direction (:ltr, :rtl, etc.)
+  # @param script [Integer, nil] Script value
+  # @param language [String, nil] BCP 47 language tag (e.g., "en")
+  # @return [ShapingResult]
+  def self.shape_text(text, font_path:, features: [], direction: nil, script: nil, language: nil)
+    blob = Blob.from_file!(font_path)
+    face = Face.new(blob, 0)
+    font = Font.new(face)
+
+    buffer = Buffer.new
+    buffer.add_utf8(text)
+    buffer.direction = direction if direction
+    buffer.script = script if script
+    buffer.language = self.language(language) if language
+    buffer.guess_segment_properties
+
+    parsed_features = case features
+                      when Array
+                        features.map { |f| f.is_a?(Feature) ? f : Feature.from_string(f.to_s) }
+                      when Hash
+                        Feature.from_hash(features)
+                      else
+                        []
+                      end
+
+    shape(font, buffer, parsed_features)
+    ShapingResult.new(buffer: buffer, font: font)
+  end
+
+  def self.build_features_ptr(features)
+    return FFI::Pointer::NULL if features.empty?
+
+    ptr = FFI::MemoryPointer.new(C::HbFeatureT, features.size)
+    features.each_with_index do |f, i|
+      s = f.to_struct
+      ptr.put_bytes(i * C::HbFeatureT.size, s.to_ptr.read_bytes(C::HbFeatureT.size))
+    end
+    ptr
+  end
+  private_class_method :build_features_ptr
+end
+
+# Alias for compatibility (Harfbuzz::VERSION was previously defined here)
+Harfbuzz = HarfBuzz unless defined?(Harfbuzz)