prawn-rtl-support 0.1.7 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da391affbc37a7e52a023f3644738dd006ffecc177374e980bb2c91735721f7f
-  data.tar.gz: 8703e5e55ef4a427ab0246667eba0b5c38fbe3c8807439cf4122f060356bcac4
+  metadata.gz: 233930e38a41afb8a807bf1753e171aa3a8112bacd425c57c8b93c2aecd374f2
+  data.tar.gz: b6ea130b2b05f7ea1f002f7023fbd22b5338324e7f0a4695175310c37d6ebb99
 SHA512:
-  metadata.gz: 29ebec9291006ad1b9d9f9eb862a067b2b26136caa8cbecbfe120ff96facf3dac647c13679c59e0a5553526d79fda6910965b27621eef75cf495ff7641b0c0ba
-  data.tar.gz: d5c27dc0a9220f14d1d8bbbf5b68ed361bc2dfce024160ccf7af71e25a15de605a8c6fbeddbcde457a60cdfc19d20dcffca643d78e334e3bc7d1d3ae72187f0c
+  metadata.gz: 882f584327fb3d2cacddb945f46a37c07fc48f0c93e0b069fd3f567359f6df226b2a7ad1ed6f604907bc912228b2acfaf34a88f06adbcde58569d97c8428298e
+  data.tar.gz: 9602c40c2e4668188f1c8d91b79587a879a50207771b247f79ea7afd9721706a5310e21793e83453b275587b7b5dc5c4e70d2fbec43e8018e277b72a2d4f58cf

data/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+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
+
+#### Added
+- **Ruby 2.7+ requirement**: Gem now explicitly requires Ruby 2.7 or higher
+- **Better documentation**: All public APIs now have YARD documentation with examples
+
+### Internal Changes
+
+#### Development & CI
+- Migrated from Travis CI to GitHub Actions
+- Added testing matrix for Ruby 2.7, 3.0, 3.1, 3.2, 3.3, and 3.4
+- Added RuboCop linting to CI workflow
+- Added Dependabot for automated dependency updates
+- Added CLAUDE.md for AI-assisted development guidance
+- Multi-factor authentication (MFA) is now required for gem publishers
+
+#### Code Quality
+- Added YARD documentation to all modules and classes
+- Fixed some RuboCop violations
+- Fixed typos
+- Improved gemspec metadata (added source_code_uri, changelog_uri, bug_tracker_uri, documentation_uri)
+- Moved development dependencies from gemspec to Gemfile
+- Removed unnecessary `$LOAD_PATH` manipulation
+- Internal file requires now use `require_relative` for faster loading
+- Gemspec file inclusion no longer depends on git, works in any environment
+
+#### Documentation
+- Updated README with "Supported Languages" section
+- Updated gemspec description to accurately reflect RTL language support
+- Added comprehensive code examples in YARD documentation
+
+## [0.1.7] - 2020-05-10
+
+For changes in previous versions, see the git commit history.

data/CLAUDE.md

@@ -0,0 +1,57 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 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 ICU for text reordering
+- Connecting Arabic letters properly for visual display
+- Minimally patching Prawn's text rendering pipeline
+
+## Development Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run test suite
+bundle exec rake spec
+# or just
+rake spec
+
+# Run linting (RuboCop)
+bundle exec rubocop
+
+# Open console for experimentation
+bin/console
+
+# Build gem locally
+bundle exec rake build
+
+# Install gem to local machine
+bundle exec rake install
+```
+
+## Architecture
+
+The gem patches Prawn by prepending a module to `Prawn::Text::Formatted::Box#original_text`. The core functionality:
+
+1. **lib/prawn/rtl/support.rb**: Main entry point that patches Prawn::Text::Formatted::Box
+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 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  
+- **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
+
+- Run tests `bundle exec rake` and RuboCop linting `bundle exec rubocop` before committing.

data/Gemfile

@@ -1,4 +1,19 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in prawn-rtl-support.gemspec
 gemspec
+
+# Development dependencies
+group :development, :test do
+  gem 'pry', '~> 0.12'
+  gem 'rake', '~> 13.0'
+  gem 'rspec', '~> 3.9'
+  gem 'rubocop', '1.80.2'
+  gem 'rubocop-performance', '1.25.0'
+  gem 'rubocop-rake', '0.7.1'
+  gem 'rubocop-rspec', '3.7.0'
+  gem 'rubocop-rubycw', '0.2.2'
+  gem 'rubocop-thread_safety', '0.7.3'
+end

data/README.md

@@ -1,15 +1,53 @@
 # Prawn::Rtl::Support
 
-[![Build Status](https://travis-ci.org/cropio/prawn-rtl-support.svg?branch=master)](https://travis-ci.org/cropio/prawn-rtl-support)
+[![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 provide bidirectional text support for Prawn. It uses Unicode Bidirectional Algorithm for displaying text from [TwitterCldr::Shared::Bidi](https://github.com/twitter/twitter-cldr-rb) and connect arabic letters using [Arabic Letter Connector](https://github.com/staii/arabic-letter-connector). Prawn patching is minimal, we patch only [`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
+
+- **Full support** (with contextual letter shaping):
+  - Arabic
+  - Persian/Farsi
+  - Urdu
+  - Other Arabic script languages
+  
+- **RTL support** (bidirectional text reordering):
+  - Hebrew
+  - Syriac
+  - Thaana
+  - Mixed LTR/RTL text
 
 ## Motivation
 
-Ruby and Rails internally provide unicode string normalization and store normalized letters inside. But Prawn don't connect arabic glyphs back and don't suport mixet LTR and RTL string. This gem add this suport. 
+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. 
 
-## Acknowledgment
-This gem use same code as [Arabic Letter Connector](https://github.com/staii/arabic-letter-connector) by [@staii](https://github.com/staii) and therefore based on [Arabic-Prawn](https://rubygems.org/gems/Arabic-Prawn/versions/0.0.1) by Dynamix Solutions (Ahmed Nasser).
+## 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
 
@@ -23,24 +61,30 @@ And that's all. Your Prawn is patched!
 
 Or install it yourself as:
 
-    $ gem install prawn-rtl-support
+```shell
+gem install prawn-rtl-support
+```
 
 ## Usage
 
-`prawn-rtl-support` provide method [`Prawn::Rtl::Connector#fix_rtl(string)`](https://github.com/cropio/prawn-rtl-support/blob/master/lib/prawn/rtl/connector.rb#L13) which reverse string and connect arabic letters.
+`prawn-rtl-support` provide method [`Prawn::Rtl::Connector#fix_rtl(string)`](https://github.com/prawn-rtl-support/prawn-rtl-support/blob/master/lib/prawn/rtl/connector.rb#L13) which reverse string and connect arabic letters.
+
 Prawn patching is minimal, we patch only [`Prawn::Text::Formatted::Box#original_text`](https://github.com/prawnpdf/prawn/blob/master/lib/prawn/text/formatted/box.rb#L367).
 
 ## Development
 
+Check [CLAUDE.md](CLAUDE.md) for more details about the architecture and development commands.
+
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/cropio/prawn-rtl-support. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
-
+Bug reports and pull requests are welcome on GitHub at https://github.com/prawn-rtl-support/prawn-rtl-support. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
+## Acknowledgment
+This gem uses the same code as [Arabic Letter Connector](https://github.com/staii/arabic-letter-connector) by [@staii](https://github.com/staii) and therefore is based on [Arabic-Prawn](https://rubygems.org/gems/Arabic-Prawn/versions/0.0.1) by Dynamix Solutions (Ahmed Nasser).
 
 ## License
 

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

@@ -3,48 +3,82 @@
 module Prawn
   module Rtl
     module Connector
+      # Handles the logic for Arabic letter connection and contextual form selection.
+      #
+      # This module implements the core algorithm for determining which form
+      # (isolated, initial, medial, or final) an Arabic character should take
+      # based on its surrounding characters. It maintains a mapping of Arabic
+      # Unicode characters to their various contextual forms.
       module Logic
-
         @@charinfos = nil
 
+        # Represents information about an Arabic character and its contextual forms.
+        #
+        # Each Arabic letter can have up to four different forms depending on
+        # its position within a word and connection to surrounding letters.
         class CharacterInfo
-          attr_accessor :common, :formatted
+          # @return [String] the base Unicode character
+          attr_accessor :common
+
+          # @return [Hash] the character's forms (:isolated, :final, :initial, :medial)
+          attr_accessor :formatted
 
+          # Initializes a new CharacterInfo instance.
+          #
+          # @param common [String] the base Unicode character
+          # @param isolated [String] the isolated form of the character
+          # @param final [String] the final form of the character
+          # @param initial [String] the initial form of the character
+          # @param medial [String] the medial form of the character
+          # @param connects [Boolean] whether this character connects to the next
+          # @param diacritic [Boolean] whether this character is a diacritic mark
           def initialize(common, isolated, final, initial, medial, connects, diacritic)
             @common = common
             @formatted = {
               isolated: isolated,
               final: final,
               initial: initial,
-              medial: medial,
+              medial: medial
             }
             @connects = connects
             @diacritic = diacritic
           end
 
+          # Checks if this character connects to the following character.
+          #
+          # @return [Boolean] true if the character connects forward
           def connects?
             @connects
           end
 
+          # Checks if this character is a diacritic mark.
+          #
+          # @return [Boolean] true if the character is a diacritic
           def diacritic?
             @diacritic
           end
-
         end
 
-        # Determine the form of the current character (:isolated, :initial, :medial,
+        # Determines the contextual form of an Arabic character.
+        #
+        # Determines the form of the current character (:isolated, :initial, :medial,
         # or :final), given the previous character and the next one. In Arabic, all
         # characters can connect with a previous character, but not all letters can
-        # connect with the next character (this is determined by
-        # CharacterInfo#connects?).
+        # connect with the next character (this is determined by CharacterInfo#connects?).
+        #
+        # @param previous_previous_char [String, nil] the character two positions before
+        # @param previous_char [String, nil] the character immediately before
+        # @param next_char [String, nil] the character immediately after
+        # @param next_next_char [String, nil] the character two positions after
+        # @return [Symbol] the contextual form (:isolated, :initial, :medial, or :final)
         def self.determine_form(previous_previous_char, previous_char, next_char, next_next_char)
           charinfos = self.charinfos
           next_char = next_next_char if charinfos[next_char] && charinfos[next_char].diacritic?
           previous_char = previous_previous_char if charinfos[previous_char] && charinfos[previous_char].diacritic?
           if charinfos[previous_char] && charinfos[next_char]
             charinfos[previous_char].connects? ? :medial : :initial # If the current character does not connect,
-                                                                    # its medial form will map to its final form,
-                                                                    # and its initial form will map to its isolated form.
+          # its medial form will map to its final form,
+          # and its initial form will map to its isolated form.
           elsif charinfos[previous_char] # The next character is not an arabic character.
             charinfos[previous_char].connects? ? :final : :isolated
           elsif charinfos[next_char] # The previous character is not an arabic character.
@@ -54,6 +88,14 @@ module Prawn
           end
         end
 
+        # Transforms Arabic text by applying contextual letter forms.
+        #
+        # Processes a string character by character, determining the appropriate
+        # contextual form for each Arabic letter based on its surrounding characters.
+        # Non-Arabic characters pass through unchanged.
+        #
+        # @param str [String] the text to transform
+        # @return [String] the transformed text with Arabic letters in their contextual forms
         def self.transform(str)
           res = ''
           charinfos = self.charinfos
@@ -69,7 +111,8 @@ module Prawn
             next_char = next_next_char
             next_next_char = char
             return unless current_char
-            if charinfos.keys.include?(current_char)
+
+            if charinfos.key?(current_char)
               form = determine_form(previous_previous_char, previous_char, next_char, next_next_char)
               res += charinfos[current_char].formatted[form]
             else
@@ -78,13 +121,19 @@ module Prawn
           end
           str.each_char { |char| consume_character.call(char) }
           2.times { consume_character.call(nil) }
-          return res
+          res
         end
 
-        private
-
+        # Returns the character information mapping for Arabic characters.
+        #
+        # Lazily initializes and returns a hash mapping Arabic Unicode characters
+        # to their CharacterInfo objects containing contextual forms.
+        #
+        # @return [Hash{String => CharacterInfo}] the character information mapping
+        # @api private
         def self.charinfos
           return @@charinfos unless @@charinfos.nil?
+
           @@charinfos = {}
           add('0627', 'fe8d', 'fe8e', 'fe8d', 'fe8e', false) # Alef
           add('0628', 'fe8f', 'fe90', 'fe91', 'fe92', true)  # Ba2
@@ -135,6 +184,16 @@ module Prawn
           @@charinfos
         end
 
+        # Adds a character and its contextual forms to the character mapping.
+        #
+        # @param common [String] hex code of the base Unicode character
+        # @param isolated [String] hex code of the isolated form
+        # @param final [String] hex code of the final form
+        # @param initial [String] hex code of the initial form
+        # @param medial [String] hex code of the medial form
+        # @param connects [Boolean] whether this character connects to the next
+        # @param diacritic [Boolean] whether this character is a diacritic mark
+        # @api private
         def self.add(common, isolated, final, initial, medial, connects, diacritic = false)
           charinfo = CharacterInfo.new(
             [common.hex].pack('U'),
@@ -147,7 +206,6 @@ module Prawn
           )
           @@charinfos[charinfo.common] = charinfo
         end
-
       end
     end
   end

data/lib/prawn/rtl/connector.rb

@@ -1,32 +1,69 @@
 # frozen_string_literal: true
 
-require 'prawn/rtl/connector/logic'
-require 'twitter_cldr'
+require_relative 'connector/logic'
+require_relative 'bidi'
 
 module Prawn
   module Rtl
+    # Provides bidirectional text support and Arabic letter connection for Prawn PDF generation.
+    #
+    # This module handles RTL (Right-to-Left) text processing by:
+    # - Connecting Arabic script letters according to their contextual forms
+    # - Reordering text using the Unicode Bidirectional Algorithm
+    # - Supporting multiple RTL languages (Arabic, Hebrew, Persian, Urdu, etc.)
+    # - Handling mixed LTR/RTL text properly
+    #
+    # @example Fix Arabic text for PDF rendering
+    #   text = "مرحبا بالعالم"
+    #   fixed_text = Prawn::Rtl::Connector.fix_rtl(text)
+    #
+    # @example Fix Hebrew text for PDF rendering
+    #   text = "שלום עולם"
+    #   fixed_text = Prawn::Rtl::Connector.fix_rtl(text)
+    #
+    # @example Fix mixed LTR/RTL text
+    #   text = "Hello مرحبا World"
+    #   fixed_text = Prawn::Rtl::Connector.fix_rtl(text)
     module Connector
+      # Connects Arabic letters according to their contextual forms.
+      #
+      # @param string [String] the text containing Arabic letters to connect
+      # @return [String] the text with properly connected Arabic letters
       def self.connect(string)
         Prawn::Rtl::Connector::Logic.transform(string)
       end
 
+      # Fixes RTL text by connecting Arabic letters and reordering for visual display.
+      #
+      # This is the main entry point for processing RTL text. It detects if the text
+      # contains RTL characters and applies both letter connection and bidirectional
+      # reordering if needed.
+      #
+      # @param string [String] the text to process
+      # @return [String] the processed text ready for PDF rendering
       def self.fix_rtl(string)
         return string unless include_rtl?(string)
+
         reorder(connect(string))
       end
 
+      # Reorders text according to the Unicode Bidirectional Algorithm.
+      #
+      # 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.
+      #
+      # @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.7'
+      VERSION = '0.2.0'
     end
   end
 end

data/lib/prawn/rtl/support.rb

@@ -1,18 +1,32 @@
 # frozen_string_literal: true
 
 require 'pdf/core/text'
-require 'prawn/rtl/support/version'
-require 'prawn/rtl/connector'
+require_relative 'support/version'
+require_relative 'connector'
 
 module Prawn
   module Rtl
+    # Main module for RTL support functionality.
     module Support
+      # Patch module that intercepts Prawn's text rendering to apply RTL transformations.
+      #
+      # This module is prepended to Prawn::Text::Formatted::Box to automatically
+      # process RTL text before rendering. It intercepts the original_text method
+      # and applies Arabic letter connection and bidirectional text reordering
+      # to any text fragments that contain RTL characters.
+      #
+      # @example How it works internally
+      #   # When Prawn renders text, this patch:
+      #   # 1. Intercepts the text fragments
+      #   # 2. Applies RTL fixes to each fragment
+      #   # 3. Returns the processed fragments for rendering
       module PrawnTextPatch
+        # Overrides the original_text method to apply RTL transformations.
+        #
+        # @return [Array<Hash>] array of text fragments with RTL text properly formatted
         def original_text
           super.map do |h|
-            if h.key?(:text)
-              h[:text] = Prawn::Rtl::Connector.fix_rtl(h[:text])
-            end
+            h[:text] = Prawn::Rtl::Connector.fix_rtl(h[:text]) if h.key?(:text)
             h
           end
         end

data/prawn-rtl-support.gemspec

@@ -1,33 +1,43 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'prawn/rtl/support/version'
+# frozen_string_literal: true
+
+require_relative 'lib/prawn/rtl/support/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "prawn-rtl-support"
+  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       = 'Gem which patch prawn to provide support of arabic language.'
-  spec.description   = 'Add suport for arabic language in prawn.'
-  spec.homepage      = "https://github.com/cropio/prawn-rtl-support"
-  spec.license       = "MIT"
+  spec.summary       = 'Bidirectional text support for Prawn PDF generator'
+  spec.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.'
+  spec.homepage      = 'https://github.com/prawn-rtl-support/prawn-rtl-support'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 2.7.0'
 
-  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features)/})
-  end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.metadata = {
+    'rubygems_mfa_required' => 'true',
+    'source_code_uri' => 'https://github.com/prawn-rtl-support/prawn-rtl-support',
+    'changelog_uri' => 'https://github.com/prawn-rtl-support/prawn-rtl-support/blob/main/CHANGELOG.md',
+    'bug_tracker_uri' => 'https://github.com/prawn-rtl-support/prawn-rtl-support/issues',
+    'documentation_uri' => 'https://rubydoc.info/gems/prawn-rtl-support'
+  }
 
-  spec.add_development_dependency 'rake', '~> 13.0'
-  spec.add_development_dependency 'rspec', '~> 3.9'
-  spec.add_development_dependency 'pry', '~> 0.12'
-  spec.add_development_dependency 'rubocop', '~> 0.77'
-  spec.add_development_dependency 'rubocop-performance', '~> 1.5'
-  spec.add_development_dependency 'rubocop-rspec', '~> 1.37'
+  # Specify which files should be included in the gem
+  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) }
+  spec.require_paths = ['lib']
+  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,99 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: prawn-rtl-support
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.2.0
 platform: ruby
 authors:
 - Oleksandr Lapchenko
-autorequire: 
+- Oleksii Leonov
 bindir: exe
 cert_chain: []
-date: 2020-05-10 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: ffi
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.9'
-- !ruby/object:Gem::Dependency
-  name: pry
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.12'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.12'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.77'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.77'
-- !ruby/object:Gem::Dependency
-  name: rubocop-performance
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.5'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.5'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.37'
-  type: :development
+        version: '1.17'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.37'
+        version: '1.17'
 - !ruby/object:Gem::Dependency
   name: prawn
   requirement: !ruby/object:Gem::Requirement
@@ -108,53 +38,40 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.2'
-- !ruby/object:Gem::Dependency
-  name: twitter_cldr
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '4.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '7.0'
-  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'
-description: Add suport for arabic language in prawn.
+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: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.md
 files:
-- ".gitignore"
-- ".rspec"
-- ".travis.yml"
+- CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
 - README.md
-- Rakefile
-- bin/console
-- bin/setup
+- lib/prawn/rtl/bidi.rb
 - lib/prawn/rtl/connector.rb
 - lib/prawn/rtl/connector/logic.rb
 - lib/prawn/rtl/support.rb
 - lib/prawn/rtl/support/version.rb
 - prawn-rtl-support.gemspec
-homepage: https://github.com/cropio/prawn-rtl-support
+homepage: https://github.com/prawn-rtl-support/prawn-rtl-support
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/prawn-rtl-support/prawn-rtl-support
+  changelog_uri: https://github.com/prawn-rtl-support/prawn-rtl-support/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/prawn-rtl-support/prawn-rtl-support/issues
+  documentation_uri: https://rubydoc.info/gems/prawn-rtl-support
 rdoc_options: []
 require_paths:
 - lib
@@ -162,15 +79,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.6.7
 specification_version: 4
-summary: Gem which patch prawn to provide support of arabic language.
+summary: Bidirectional text support for Prawn PDF generator
 test_files: []

data/.gitignore

@@ -1,14 +0,0 @@
-/.bundle/
-/.yardoc
-/Gemfile.lock
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-
-# rspec failure tracking
-.rspec_status
-
-*.gem

data/.rspec

@@ -1,2 +0,0 @@
---format documentation
---color

data/.travis.yml

@@ -1,7 +0,0 @@
-language: ruby
-rvm:
-  - 2.6
-  - 2.5
-  - 2.4
-before_install:
-  - gem install bundler

data/Rakefile

@@ -1,6 +0,0 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-task :default => :spec

data/bin/console

@@ -1,14 +0,0 @@
-#!/usr/bin/env ruby
-
-require "bundler/setup"
-require "prawn/rtl/support"
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "pry"
-Pry.start(__FILE__)

data/bin/setup

@@ -1,8 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
-
-bundle install
-
-# Do any other automated setup that you need to do here