prawn-rtl-support 0.1.8 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1424d40245ffbe3f42623e759747cdf847a9ca998df21164a2e08c800417fe1e
-  data.tar.gz: abad0e4cc7958ef0f3fd4213eb50ecb02bfa121312a1cab18b2418c568ec4427
+  metadata.gz: 233930e38a41afb8a807bf1753e171aa3a8112bacd425c57c8b93c2aecd374f2
+  data.tar.gz: b6ea130b2b05f7ea1f002f7023fbd22b5338324e7f0a4695175310c37d6ebb99
 SHA512:
-  metadata.gz: 7bef93dc5aa91ba1869881d51a109f305f1e9c4567be688333503c10714efdb448deba04634053c23351e9f8c5b8f85e87df08c6f702ba2e4347b15bd13ab5ca
-  data.tar.gz: fbd89cc337db56fd6c3f369c745f125b95fbaa099ab6e1783a354cb5cb90d5d3b8024692fc74a5debc3ad45e881bbf6e92e83d2716522d872a559e1ea9e4d8c3
+  metadata.gz: 882f584327fb3d2cacddb945f46a37c07fc48f0c93e0b069fd3f567359f6df226b2a7ad1ed6f604907bc912228b2acfaf34a88f06adbcde58569d97c8428298e
+  data.tar.gz: 9602c40c2e4668188f1c8d91b79587a879a50207771b247f79ea7afd9721706a5310e21793e83453b275587b7b5dc5c4e70d2fbec43e8018e277b72a2d4f58cf

data/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2025-09-04
+
+### ⚠️ Breaking Changes
+- **ICU library requirement**: The gem now requires the ICU library to be installed on the system. This may affect macOS and Windows users who previously relied on twitter_cldr's bundled ICU data.
+  - **Linux**: Usually pre-installed
+  - **macOS**: Install via Homebrew: `brew install icu4c`
+  - **Windows**: May require manual ICU installation
+  - **Custom path**: Set `ICU_LIB_PATH` environment variable if ICU is installed in a non-standard location
+
+### Customer-Impacting Changes
+
+#### Added
+- **Extended platform support**: Added ARM64 architecture support in CI/CD pipeline
+
+#### Changed
+- **Dependencies**: Replaced twitter_cldr with direct FFI bindings (lighter dependency footprint, but requires system ICU library)
+- **Performance**: Direct ICU integration provides better performance for text processing
+
+### Internal Changes
+
+#### Testing & Quality
+- Added comprehensive integration tests for BiDi functionality
+- Extended CI matrix to include Ubuntu 22.04, 24.04 and ARM64 variants
+
 ## [0.1.8] - 2025-09-04
 
 ### Customer-Impacting Changes

data/CLAUDE.md

@@ -5,7 +5,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Project Overview
 
 This is prawn-rtl-support, a Ruby gem that provides bidirectional text (RTL/LTR) support for the Prawn PDF generation library. It enables proper rendering of Arabic and other right-to-left languages in PDFs by:
-- Using Unicode Bidirectional Algorithm via TwitterCldr for text reordering
+- Using Unicode Bidirectional Algorithm via ICU for text reordering
 - Connecting Arabic letters properly for visual display
 - Minimally patching Prawn's text rendering pipeline
 
@@ -41,15 +41,16 @@ The gem patches Prawn by prepending a module to `Prawn::Text::Formatted::Box#ori
 2. **lib/prawn/rtl/connector.rb**: Core RTL fixing logic with three main methods:
    - `fix_rtl(string)`: Main public API that detects RTL text and processes it
    - `connect(string)`: Applies Arabic letter connection rules
-   - `reorder(string)`: Uses TwitterCldr's Bidi algorithm to reorder text visually
+   - `reorder(string)`: Uses ICU's Bidi algorithm to reorder text visually
 3. **lib/prawn/rtl/connector/logic.rb**: Arabic letter connection logic with character mapping tables for different forms (isolated, initial, medial, final)
 
 The gem automatically activates when required - no configuration needed. It detects RTL text and only processes strings that contain RTL characters.
 
 ## Key Dependencies
 
-- **prawn ~> 2.2**: The PDF generation library being patched
-- **twitter_cldr >= 4.0, < 7.0**: Provides Unicode Bidirectional Algorithm implementation
+- **prawn ~> 2.2**: The PDF generation library being patched  
+- **ffi ~> 1.15**: Foreign Function Interface for Ruby to call ICU C library functions
+- **ICU library**: System dependency (libicuuc) providing Unicode Bidirectional Algorithm implementation
 
 ## Contributing
 

data/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/prawn-rtl-support/prawn-rtl-support/actions/workflows/ci.yml/badge.svg)](https://github.com/prawn-rtl-support/prawn-rtl-support/actions/workflows/ci.yml)
 
-This gem provides bidirectional text support for Prawn PDF generator. It uses the Unicode Bidirectional Algorithm from [TwitterCldr::Shared::Bidi](https://github.com/twitter/twitter-cldr-rb) for text reordering and implements Arabic letter shaping similar to [Arabic Letter Connector](https://github.com/staii/arabic-letter-connector). Prawn patching is minimal - we only patch [`Prawn::Text::Formatted::Box#original_text`](https://github.com/prawnpdf/prawn/blob/master/lib/prawn/text/formatted/box.rb#L367).
+This gem provides bidirectional text support for Prawn PDF generator. It uses the Unicode Bidirectional Algorithm via [ICU](http://site.icu-project.org/) (International Components for Unicode) for text reordering and implements Arabic letter shaping similar to [Arabic Letter Connector](https://github.com/staii/arabic-letter-connector). Prawn patching is minimal - we only patch [`Prawn::Text::Formatted::Box#original_text`](https://github.com/prawnpdf/prawn/blob/master/lib/prawn/text/formatted/box.rb#L367).
 
 ## Supported Languages
 
@@ -22,6 +22,33 @@ This gem provides bidirectional text support for Prawn PDF generator. It uses th
 
 Ruby and Rails internally provide Unicode string normalization. However, Prawn doesn't connect Arabic letters into their contextual forms and doesn't support mixed LTR and RTL strings. This gem adds this support. 
 
+## Requirements
+
+### ICU Library
+
+Starting from version 0.2.0, this gem requires the ICU library to be installed on your system:
+
+- **Linux**: Usually pre-installed. If not, install with:
+  ```bash
+  # Ubuntu/Debian
+  sudo apt-get install libicu-dev
+  
+  # RHEL/CentOS/Fedora
+  sudo yum install libicu-devel
+  ```
+
+- **macOS**: Install via Homebrew:
+  ```bash
+  brew install icu4c
+  ```
+
+- **Windows**: Download and install ICU from the [official site](http://site.icu-project.org/download)
+
+- **Custom installation path**: If ICU is installed in a non-standard location, set the `ICU_LIB_PATH` environment variable:
+  ```bash
+  export ICU_LIB_PATH=/custom/path/to/icu/lib
+  ```
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/lib/prawn/rtl/bidi.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+require 'ffi'
+
+module Prawn
+  module Rtl
+    # FFI BiDi wrapper for Unicode Bidirectional Algorithm support
+    #
+    # This module provides direct FFI bindings to ICU's ubidi functions
+    # for bidirectional text processing.
+    module Bidi
+      extend FFI::Library
+
+      class BiDiError < StandardError; end
+
+      # Detect platform
+      def self.platform
+        os = RbConfig::CONFIG['host_os']
+        case os
+        when /darwin/
+          :osx
+        when /linux/
+          :linux
+        when /bsd/
+          :bsd
+        when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+          :windows
+        else
+          :linux
+        end
+      end
+
+      # Search paths for ICU libraries
+      def self.search_paths
+        @search_paths ||=
+          if ENV['ICU_LIB_PATH']
+            [ENV['ICU_LIB_PATH']]
+          elsif FFI::Platform::IS_WINDOWS
+            ENV['PATH'].split(File::PATH_SEPARATOR)
+          else
+            [
+              '/usr/local/{lib64,lib}',
+              '/opt/local/{lib64,lib}',
+              '/opt/homebrew/{lib64,lib}',
+              '/usr/{lib64,lib}'
+            ] + Dir['/usr/lib/*-linux-gnu'] + Dir['/lib/*-linux-gnu']
+          end
+      end
+
+      # Find ICU library files
+      def self.find_icu_lib
+        candidates = []
+        lib_name = 'icuuc'
+
+        search_paths.each do |path|
+          Dir.glob(File.expand_path(path)).each do |dir|
+            # Try versioned libraries first (newer to older)
+            # ICU versions from 4.0 (2009) to potential future versions
+            90.downto(4).each do |version|
+              case platform
+              when :osx
+                candidates << File.join(dir, "lib#{lib_name}.#{version}.dylib")
+                candidates << File.join(dir, "lib#{lib_name}.dylib")
+              when :windows
+                candidates << File.join(dir, "#{lib_name}#{version}.dll")
+                candidates << File.join(dir, "#{lib_name}.dll")
+              else
+                candidates << File.join(dir, "lib#{lib_name}.so.#{version}")
+                candidates << File.join(dir, "lib#{lib_name}.so")
+              end
+            end
+          end
+        end
+
+        # Find the first existing library
+        found = candidates.find { |path| File.exist?(path) }
+        found || ["lib#{lib_name}.so", "lib#{lib_name}.dylib", "#{lib_name}.dll", lib_name]
+      end
+
+      # Load the library
+      ffi_lib find_icu_lib
+
+      # Detect ICU version suffix by checking for a known function
+      def self.detect_icu_suffix
+        @detect_icu_suffix ||= begin
+          # Try common suffixes from newer to older versions
+          # Some versions use _4_2 format, others use _42 format
+          suffixes = [''] + 90.downto(4).flat_map { |v| ["_#{v}", "_#{v / 10}_#{v % 10}"] }
+
+          # Find suffix by checking if ubidi_open function exists
+          suffix = suffixes.find do |s|
+            # Try to find the function
+            func_name = :"ubidi_open#{s}"
+            ffi_libraries.any? do |lib|
+              lib.find_function(func_name.to_s)
+            end
+          rescue StandardError
+            false
+          end
+
+          suffix || ''
+        end
+      end
+
+      # Helper to attach function with detected suffix
+      def self.attach_icu_function(ruby_name, icu_name, args, return_type)
+        suffixed_name = "#{icu_name}#{detect_icu_suffix}"
+        attach_function ruby_name, suffixed_name.to_sym, args, return_type
+      end
+
+      # Constants from ubidi.h
+      UBIDI_DEFAULT_LTR = 0xfe
+      UBIDI_DEFAULT_RTL = 0xff
+      UBIDI_LTR = 0
+      UBIDI_RTL = 1
+      UBIDI_MIXED = 2
+      UBIDI_NEUTRAL = 3
+
+      # Reorder options
+      UBIDI_DO_MIRRORING = 2
+      UBIDI_OUTPUT_REVERSE = 16
+
+      # Attach ICU functions with version detection
+      attach_icu_function :ubidi_open, 'ubidi_open', [], :pointer
+      attach_icu_function :ubidi_close, 'ubidi_close', [:pointer], :void
+      attach_icu_function :ubidi_setPara, 'ubidi_setPara', %i[pointer pointer int32 uint8 pointer pointer], :void
+      attach_icu_function :ubidi_getDirection, 'ubidi_getDirection', [:pointer], :int
+      attach_icu_function :ubidi_getLength, 'ubidi_getLength', [:pointer], :int32
+      attach_icu_function :ubidi_writeReordered, 'ubidi_writeReordered', %i[pointer pointer int32 uint16 pointer],
+                          :int32
+      attach_icu_function :ubidi_countRuns, 'ubidi_countRuns', %i[pointer pointer], :int32
+
+      # Reorders text according to the Unicode Bidirectional Algorithm
+      #
+      # @param text [String] the text to reorder
+      # @param direction [Symbol] :ltr, :rtl, or :auto (default)
+      # @return [String] the visually reordered text
+      def self.reorder(text, direction: :auto)
+        return text if text.nil? || text.empty?
+
+        # Convert direction to ubidi constant
+        para_level =
+          case direction
+          when :ltr then UBIDI_LTR
+          when :rtl then UBIDI_RTL
+          else UBIDI_DEFAULT_LTR
+          end
+
+        bidi = nil
+        begin
+          # Open BiDi object
+          bidi = ubidi_open
+          raise BiDiError, 'Failed to create BiDi object' if bidi.null?
+
+          # Convert string to UTF-16 for ICU
+          utf16_text = text.encode('UTF-16LE')
+          text_length = utf16_text.bytesize / 2
+
+          # Create buffer for UTF-16 string
+          text_buffer = FFI::MemoryPointer.new(:uint16, text_length + 1)
+          text_buffer.put_bytes(0, utf16_text)
+
+          # Error status
+          status = FFI::MemoryPointer.new(:int32)
+          status.put_int32(0, 0)
+
+          # Set paragraph
+          ubidi_setPara(bidi, text_buffer, text_length, para_level, nil, status)
+
+          error_code = status.get_int32(0)
+          raise BiDiError, "ubidi_setPara failed with error code: #{error_code}" if error_code.positive?
+
+          # Get required size for output
+          output_length = text_length * 2
+          output_buffer = FFI::MemoryPointer.new(:uint16, output_length)
+
+          # Write reordered text
+          written = ubidi_writeReordered(bidi, output_buffer, output_length, UBIDI_DO_MIRRORING, status)
+
+          error_code = status.get_int32(0)
+          raise BiDiError, "ubidi_writeReordered failed with error code: #{error_code}" if error_code.positive?
+
+          # Convert back from UTF-16 to UTF-8
+          result_bytes = output_buffer.get_bytes(0, written * 2)
+          result_bytes.force_encoding('UTF-16LE').encode('UTF-8')
+        ensure
+          ubidi_close(bidi) if bidi && !bidi.null?
+        end
+      end
+
+      # Checks if a string contains RTL characters
+      #
+      # @param text [String] the text to check
+      # @return [Boolean] true if the text contains RTL characters
+      def self.contains_rtl?(text)
+        return false if text.nil? || text.empty?
+
+        bidi = nil
+        begin
+          bidi = ubidi_open
+          return false if bidi.null?
+
+          utf16_text = text.encode('UTF-16LE')
+          text_length = utf16_text.bytesize / 2
+
+          text_buffer = FFI::MemoryPointer.new(:uint16, text_length + 1)
+          text_buffer.put_bytes(0, utf16_text)
+
+          status = FFI::MemoryPointer.new(:int32)
+          status.put_int32(0, 0)
+
+          ubidi_setPara(bidi, text_buffer, text_length, UBIDI_DEFAULT_LTR, nil, status)
+
+          return false if status.get_int32(0).positive?
+
+          direction = ubidi_getDirection(bidi)
+          [UBIDI_RTL, UBIDI_MIXED].include?(direction)
+        ensure
+          ubidi_close(bidi) if bidi && !bidi.null?
+        end
+      end
+    end
+  end
+end

data/lib/prawn/rtl/connector.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'connector/logic'
-require 'twitter_cldr'
+require_relative 'bidi'
 
 module Prawn
   module Rtl
@@ -49,16 +49,13 @@ module Prawn
 
       # Reorders text according to the Unicode Bidirectional Algorithm.
       #
-      # Uses TwitterCldr's Bidi implementation to visually reorder mixed
+      # Uses ICU's BiDi implementation via FFI to visually reorder mixed
       # LTR/RTL text for correct display.
       #
       # @param string [String] the text to reorder
       # @return [String] the visually reordered text
       def self.reorder(string)
-        TwitterCldr::Shared::Bidi
-          .from_string(string, direction: :RTL)
-          .reorder_visually!
-          .to_s
+        Bidi.reorder(string, direction: :rtl)
       end
 
       # Checks if a string contains RTL (Right-to-Left) characters.
@@ -66,10 +63,7 @@ module Prawn
       # @param string [String] the text to check
       # @return [Boolean] true if the text contains RTL characters, false otherwise
       def self.include_rtl?(string)
-        TwitterCldr::Shared::Bidi
-          .from_string(string)
-          .types
-          .include?(:R)
+        Bidi.contains_rtl?(string)
       end
     end
   end

data/lib/prawn/rtl/support/version.rb

@@ -3,7 +3,7 @@
 module Prawn
   module Rtl
     module Support
-      VERSION = '0.1.8'
+      VERSION = '0.2.0'
     end
   end
 end

data/prawn-rtl-support.gemspec

@@ -5,8 +5,8 @@ require_relative 'lib/prawn/rtl/support/version'
 Gem::Specification.new do |spec|
   spec.name          = 'prawn-rtl-support'
   spec.version       = Prawn::Rtl::Support::VERSION
-  spec.authors       = ['Oleksandr Lapchenko']
-  spec.email         = ['ozeron@me.com']
+  spec.authors       = ['Oleksandr Lapchenko', 'Oleksii Leonov']
+  spec.email         = ['ozeron@me.com', 'mail@oleksiileonov.com']
 
   spec.summary       = 'Bidirectional text support for Prawn PDF generator'
   spec.description   = 'Adds right-to-left (RTL) text support to Prawn PDF generator. ' \
@@ -26,10 +26,11 @@ Gem::Specification.new do |spec|
   }
 
   # Specify which files should be included in the gem
-  spec.files = (Dir['{lib,exe}/**/*'] +
-                Dir['*.{md,txt,gemspec}'] +
-                %w[Gemfile Rakefile LICENSE.txt README.md CODE_OF_CONDUCT.md].select { |f| File.exist?(f) })
-               .reject { |f| File.directory?(f) }
+  spec.files = (
+    Dir['{lib,exe}/**/*'] +
+    Dir['*.{md,txt,gemspec}'] +
+    %w[Gemfile LICENSE.txt README.md CODE_OF_CONDUCT.md].select { |f| File.exist?(f) }
+  ).reject { |f| File.directory?(f) }
 
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
@@ -37,6 +38,6 @@ Gem::Specification.new do |spec|
   spec.extra_rdoc_files = ['README.md', 'LICENSE.txt']
 
   # Runtime dependencies
+  spec.add_dependency 'ffi', '~> 1.17'
   spec.add_dependency 'prawn', '~> 2.2'
-  spec.add_dependency 'twitter_cldr', '>= 4.0', '< 7.0'
 end

metadata

@@ -1,54 +1,50 @@
 --- !ruby/object:Gem::Specification
 name: prawn-rtl-support
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.2.0
 platform: ruby
 authors:
 - Oleksandr Lapchenko
+- Oleksii Leonov
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: prawn
+  name: ffi
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: '1.17'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: '1.17'
 - !ruby/object:Gem::Dependency
-  name: twitter_cldr
+  name: prawn
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '4.0'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '2.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '4.0'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '2.2'
 description: Adds right-to-left (RTL) text support to Prawn PDF generator. Fully supports
   Arabic script languages (Arabic, Persian, Urdu) with contextual letter shaping and
   ligatures. Also supports Hebrew and other RTL languages with bidirectional text
   reordering. Handles mixed LTR/RTL text properly.
 email:
 - ozeron@me.com
+- mail@oleksiileonov.com
 executables: []
 extensions: []
 extra_rdoc_files:
@@ -61,7 +57,7 @@ files:
 - Gemfile
 - LICENSE.txt
 - README.md
-- Rakefile
+- lib/prawn/rtl/bidi.rb
 - lib/prawn/rtl/connector.rb
 - lib/prawn/rtl/connector/logic.rb
 - lib/prawn/rtl/support.rb

data/Rakefile

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-
-RSpec::Core::RakeTask.new(:spec)
-
-task default: :spec