rphonetic 0.1.0

data/lib/rphonetic/encoder.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module RPhonetic
+  # Shared interface for reusable native phonetic encoders.
+  # Each instance owns its native encoder. Class convenience methods accept
+  # the same keywords as the concrete encoder's constructor.
+  #
+  # @abstract Instantiate a concrete algorithm, such as DoubleMetaphone.
+  class Encoder
+    class << self
+      # Construct an encoder and encode one name.
+      # Reuse an instance when encoding repeatedly, especially with external rules.
+      #
+      # @param value [String] name to encode
+      # @param options [Hash] keyword arguments accepted by the subclass constructor
+      # @return [String] the single or primary code, or Beider–Morse expression
+      # @see #encode
+      def encode(value, **options)
+        new(**options).encode(value)
+      end
+
+      # Construct an encoder and encode several names in input order.
+      #
+      # @param values [Array<String>] names to encode
+      # @param options [Hash] keyword arguments accepted by the subclass constructor
+      # @return [Array<String>] one result per input name
+      # @see #encode_many
+      def encode_many(values, **options)
+        new(**options).encode_many(values)
+      end
+    end
+
+    # Encode one name using this instance's configuration.
+    # Strings are transcoded to UTF-8; no transliteration is performed.
+    #
+    # @param value [String] name to encode
+    # @return [String] the single or primary code, or Beider–Morse expression
+    # @raise [TypeError] if value is not a String
+    # @raise [ArgumentError] if the string contains invalid bytes, or an ASCII-only encoder receives non-ASCII text
+    # @raise [EncodingError] if the string cannot be transcoded to UTF-8
+    # @raise [RuntimeError] if the upstream encoder panics
+    def encode(value)
+      @native.encode(text(value))
+    end
+
+    # Encode an array in one native call, preserving input order.
+    # Returns an empty array for empty input. Beider–Morse guesses languages
+    # for each name. This call holds Ruby's GVL.
+    #
+    # @param values [Array<String>] names to encode
+    # @return [Array<String>] one result per input name
+    # @raise [TypeError] if values is not an Array or contains a non-String
+    # @raise [ArgumentError, EncodingError, RuntimeError] for the same input or upstream errors as #encode
+    # @see #encode
+    def encode_many(values)
+      raise TypeError, "values must be an Array" unless values.is_a?(Array)
+      @native.encode_many(values.map { |value| text(value) })
+    end
+
+    # Compare two names using the upstream algorithm.
+    # Match Rating Approach uses its similarity rating. Other encoders compare
+    # {#encode} results: Double Metaphone uses primary codes, Daitch–Mokotoff
+    # uses nonbranching codes, and Beider–Morse compares entire expressions.
+    # This does not check for overlap between alternative codes.
+    #
+    # @param first [String] first name
+    # @param second [String] second name
+    # @return [Boolean] whether the algorithm considers the names equivalent
+    # @raise [TypeError, ArgumentError, EncodingError, RuntimeError] for the same input or upstream errors as #encode
+    def match?(first, second)
+      @native.matches(text(first), text(second))
+    end
+
+    private
+
+    def text(value)
+      raise TypeError, "value must be a String" unless value.is_a?(String)
+      raise ArgumentError, "value contains invalid bytes" unless value.valid_encoding?
+      value.encode(Encoding::UTF_8)
+    end
+
+    def length_option(value, name, unlimited: false)
+      return nil if unlimited && value.nil?
+      raise ArgumentError, "#{name} must be a positive Integer#{' or nil' if unlimited}" unless value.is_a?(Integer) && value.positive?
+      value
+    end
+
+    def boolean(value, name)
+      raise ArgumentError, "#{name} must be true or false" unless value == true || value == false
+      value
+    end
+  end
+end

data/lib/rphonetic/encoders.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "encoder"
+require_relative "caverphone1"
+require_relative "caverphone2"
+require_relative "cologne"
+require_relative "match_rating_approach"
+require_relative "metaphone"
+require_relative "double_metaphone"
+require_relative "nysiis"
+require_relative "phonex"
+require_relative "soundex"
+require_relative "refined_soundex"
+require_relative "daitch_mokotoff_soundex"
+require_relative "beider_morse"
+
+module RPhonetic
+  private_constant :NativeEncoder
+end

data/lib/rphonetic/match_rating_approach.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RPhonetic
+  # Match Rating Approach encodes names in at most six characters.
+  # Unlike the other encoders, {#match?} applies the algorithm's similarity
+  # rating rather than requiring identical codes.
+  #
+  # @example
+  #   encoder = RPhonetic::MatchRatingApproach.new
+  #   encoder.encode("Smith")       # => "SMTH"
+  #   encoder.match?("Smith", "Smyth") # => true
+  class MatchRatingApproach < Encoder
+    # Create a MatchRatingApproach encoder. This algorithm has no configuration options.
+    def initialize
+      @native = NativeEncoder.simple("MatchRatingApproach")
+    end
+  end
+end

data/lib/rphonetic/metaphone.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RPhonetic
+  # Metaphone encodes English pronunciation as a single phonetic code.
+  #
+  # @example
+  #   RPhonetic::Metaphone.encode("Joanne") # => "JN"
+  class Metaphone < Encoder
+    # Create a Metaphone encoder.
+    #
+    # @param max_length [Integer, nil] positive maximum code length; nil removes the limit
+    # @raise [ArgumentError] if max_length is neither positive nor nil
+    def initialize(max_length: 4)
+      @native = NativeEncoder.metaphone(length_option(max_length, :max_length, unlimited: true))
+    end
+  end
+end

data/lib/rphonetic/nysiis.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RPhonetic
+  # New York State Identification and Intelligence System phonetic encoding.
+  # Strict mode limits the result to six characters.
+  #
+  # @example
+  #   RPhonetic::Nysiis.encode("WESTERLUND")                # => "WASTAR"
+  #   RPhonetic::Nysiis.encode("WESTERLUND", strict: false) # => "WASTARLAD"
+  class Nysiis < Encoder
+    # Create a NYSIIS encoder.
+    #
+    # @param strict [Boolean] whether to truncate the code to six characters
+    # @raise [ArgumentError] if strict is not true or false
+    def initialize(strict: true)
+      @native = NativeEncoder.nysiis(boolean(strict, :strict))
+    end
+  end
+end

data/lib/rphonetic/phonex.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RPhonetic
+  # Phonex combines Soundex-style codes with pronunciation normalization.
+  # Codes are padded with zeroes to the configured length.
+  #
+  # @example
+  #   RPhonetic::Phonex.encode("William") # => "W450"
+  class Phonex < Encoder
+    # Create a Phonex encoder.
+    #
+    # @param max_length [Integer] positive code length; nil is not supported
+    # @raise [ArgumentError] if max_length is not a positive Integer
+    def initialize(max_length: 4)
+      @native = NativeEncoder.phonex(length_option(max_length, :max_length))
+    end
+  end
+end

data/lib/rphonetic/refined_soundex.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module RPhonetic
+  # Refined Soundex uses more consonant groups than Soundex and returns
+  # variable-length codes. Input names must be ASCII; non-ASCII names raise
+  # ArgumentError.
+  #
+  # @example
+  #   RPhonetic::RefinedSoundex.encode("jumped") # => "J408106"
+  class RefinedSoundex < Encoder
+    # Default code mapping for the letters A–Z.
+    # @return [String]
+    DEFAULT_MAPPING = "01360240043788015936020505"
+
+    # Create a Refined Soundex encoder.
+    #
+    # @param mapping [String] exactly 26 characters, one per letter A–Z
+    # @raise [TypeError] if mapping is not a String
+    # @raise [ArgumentError] if the mapping is invalid
+    def initialize(mapping: DEFAULT_MAPPING)
+      @native = NativeEncoder.refined_soundex(text(mapping))
+    end
+
+    # Count positions at which the two encoded names have the same character.
+    # This is a similarity count, not an edit distance.
+    #
+    # @param first [String] first ASCII name
+    # @param second [String] second ASCII name
+    # @return [Integer] number of equal positions, from zero through the shorter code's length
+    # @raise [TypeError, ArgumentError, EncodingError, RuntimeError] for the same input or upstream errors as #encode
+    def difference(first, second)
+      @native.difference(text(first), text(second))
+    end
+  end
+end

data/lib/rphonetic/soundex.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RPhonetic
+  # Soundex encodes a name as its initial letter followed by three digits.
+  # Input names must be ASCII; non-ASCII names raise ArgumentError.
+  #
+  # @example
+  #   RPhonetic::Soundex.encode("Robert") # => "R163"
+  class Soundex < Encoder
+    # Default code mapping for the letters A–Z.
+    # @return [String]
+    DEFAULT_MAPPING = "01230120022455012623010202"
+    # Genealogical mapping; hyphens mark letters that are ignored.
+    # @return [String]
+    GENEALOGY_MAPPING = "-123-12--22455-12623-1-2-2"
+
+    # Create a Soundex encoder with a standard or custom A–Z mapping.
+    #
+    # @param mapping [String] exactly 26 characters, one per letter A–Z
+    # @param special_case_h_w [Boolean] whether H and W leave the preceding code unchanged
+    # @raise [TypeError] if mapping is not a String
+    # @raise [ArgumentError] if the mapping is invalid or special_case_h_w is not a Boolean
+    def initialize(mapping: DEFAULT_MAPPING, special_case_h_w: true)
+      @native = NativeEncoder.soundex(text(mapping), boolean(special_case_h_w, :special_case_h_w))
+    end
+
+    # Count positions at which the two encoded names have the same character.
+    # This is a similarity count, not an edit distance.
+    #
+    # @param first [String] first ASCII name
+    # @param second [String] second ASCII name
+    # @return [Integer] number of equal positions, from zero through the shorter code's length
+    # @raise [TypeError, ArgumentError, EncodingError, RuntimeError] for the same input or upstream errors as #encode
+    def difference(first, second)
+      @native.difference(text(first), text(second))
+    end
+  end
+end

data/lib/rphonetic/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module RPhonetic
+  # Ruby gem version, independent of the wrapped Rust crate's version.
+  VERSION = "0.1.0"
+end

data/lib/rphonetic.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require_relative "rphonetic/version"
+
+# Ruby bindings for the rphonetic Rust phonetic algorithms.
+# Encoders are reusable and accept valid Strings, transcoded to UTF-8.
+module RPhonetic
+  # Raised when caller-supplied rules cannot be loaded or parsed.
+  class RuleError < ArgumentError; end
+end
+
+series = RUBY_VERSION.split(".").first(2).join(".")
+binary = File.expand_path("rphonetic/#{series}/rphonetic_ext.#{RbConfig::CONFIG.fetch('DLEXT')}", __dir__)
+local_binary = File.expand_path("rphonetic/rphonetic_ext.#{RbConfig::CONFIG.fetch('DLEXT')}", __dir__)
+if File.file?(local_binary)
+  # A fresh development build takes precedence over staged release artifacts.
+  require local_binary
+elsif File.file?(binary)
+  require binary
+else
+  require "rphonetic/rphonetic_ext"
+end
+
+require_relative "rphonetic/encoders"

data/sig/rphonetic/beider_morse.rbs

@@ -0,0 +1,14 @@
+module RPhonetic
+  class BeiderMorse < Encoder
+    type name_type = :generic | :ashkenazi | :sephardic | "generic" | "ashkenazi" | "sephardic"
+    type rule_type = :approx | :exact | "approx" | "exact"
+    type languages = Array[String] | :any | nil
+
+    def initialize: (rules_path: String, ?name_type: name_type, ?rule_type: rule_type, ?concat: bool, ?max_phonemes: Integer) -> void
+    def self.encode: (String value, rules_path: String, ?name_type: name_type, ?rule_type: rule_type, ?concat: bool, ?max_phonemes: Integer) -> String
+    def self.encode_many: (Array[String] values, rules_path: String, ?name_type: name_type, ?rule_type: rule_type, ?concat: bool, ?max_phonemes: Integer) -> Array[String]
+
+    # Only instance encoding accepts explicit languages.
+    def encode: (String value, ?languages: languages) -> String
+  end
+end

data/sig/rphonetic/caverphone1.rbs

@@ -0,0 +1,5 @@
+module RPhonetic
+  class Caverphone1 < Encoder
+    def initialize: () -> void
+  end
+end

data/sig/rphonetic/caverphone2.rbs

@@ -0,0 +1,5 @@
+module RPhonetic
+  class Caverphone2 < Encoder
+    def initialize: () -> void
+  end
+end

data/sig/rphonetic/cologne.rbs

@@ -0,0 +1,5 @@
+module RPhonetic
+  class Cologne < Encoder
+    def initialize: () -> void
+  end
+end

data/sig/rphonetic/daitch_mokotoff_soundex.rbs

@@ -0,0 +1,9 @@
+module RPhonetic
+  class DaitchMokotoffSoundex < Encoder
+    def initialize: (rules: String, ?ascii_folding: bool) -> void
+    def self.encode: (String value, rules: String, ?ascii_folding: bool) -> String
+    def self.encode_many: (Array[String] values, rules: String, ?ascii_folding: bool) -> Array[String]
+
+    def codes: (String value) -> Array[String]
+  end
+end

data/sig/rphonetic/double_metaphone.rbs

@@ -0,0 +1,11 @@
+module RPhonetic
+  class DoubleMetaphone < Encoder
+    def initialize: (?max_length: Integer?) -> void
+    def self.encode: (String value, ?max_length: Integer?) -> String
+    def self.encode_many: (Array[String] values, ?max_length: Integer?) -> Array[String]
+
+    def self.codes: (String value, ?max_length: Integer?) -> [String, String]
+    def codes: (String value) -> [String, String]
+    def alternate: (String value) -> String
+  end
+end

data/sig/rphonetic/encoder.rbs

@@ -0,0 +1,11 @@
+module RPhonetic
+  # Abstract shared interface; instantiate a concrete algorithm.
+  class Encoder
+    def self.encode: (String value) -> String
+    def self.encode_many: (Array[String] values) -> Array[String]
+
+    def encode: (String value) -> String
+    def encode_many: (Array[String] values) -> Array[String]
+    def match?: (String first, String second) -> bool
+  end
+end

data/sig/rphonetic/match_rating_approach.rbs

@@ -0,0 +1,5 @@
+module RPhonetic
+  class MatchRatingApproach < Encoder
+    def initialize: () -> void
+  end
+end

data/sig/rphonetic/metaphone.rbs

@@ -0,0 +1,7 @@
+module RPhonetic
+  class Metaphone < Encoder
+    def initialize: (?max_length: Integer?) -> void
+    def self.encode: (String value, ?max_length: Integer?) -> String
+    def self.encode_many: (Array[String] values, ?max_length: Integer?) -> Array[String]
+  end
+end

data/sig/rphonetic/nysiis.rbs

@@ -0,0 +1,7 @@
+module RPhonetic
+  class Nysiis < Encoder
+    def initialize: (?strict: bool) -> void
+    def self.encode: (String value, ?strict: bool) -> String
+    def self.encode_many: (Array[String] values, ?strict: bool) -> Array[String]
+  end
+end

data/sig/rphonetic/phonex.rbs

@@ -0,0 +1,7 @@
+module RPhonetic
+  class Phonex < Encoder
+    def initialize: (?max_length: Integer) -> void
+    def self.encode: (String value, ?max_length: Integer) -> String
+    def self.encode_many: (Array[String] values, ?max_length: Integer) -> Array[String]
+  end
+end

data/sig/rphonetic/refined_soundex.rbs

@@ -0,0 +1,11 @@
+module RPhonetic
+  class RefinedSoundex < Encoder
+    DEFAULT_MAPPING: String
+
+    def initialize: (?mapping: String) -> void
+    def self.encode: (String value, ?mapping: String) -> String
+    def self.encode_many: (Array[String] values, ?mapping: String) -> Array[String]
+
+    def difference: (String first, String second) -> Integer
+  end
+end

data/sig/rphonetic/soundex.rbs

@@ -0,0 +1,12 @@
+module RPhonetic
+  class Soundex < Encoder
+    DEFAULT_MAPPING: String
+    GENEALOGY_MAPPING: String
+
+    def initialize: (?mapping: String, ?special_case_h_w: bool) -> void
+    def self.encode: (String value, ?mapping: String, ?special_case_h_w: bool) -> String
+    def self.encode_many: (Array[String] values, ?mapping: String, ?special_case_h_w: bool) -> Array[String]
+
+    def difference: (String first, String second) -> Integer
+  end
+end

data/sig/rphonetic.rbs

@@ -0,0 +1,7 @@
+module RPhonetic
+  VERSION: String
+
+  # Errors while loading or parsing caller-supplied phonetic rules.
+  class RuleError < ArgumentError
+  end
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: rphonetic
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- tzaid
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Reusable encoders for all twelve rphonetic algorithms, with caller-supplied
+  rules and precompiled native gem support.
+executables: []
+extensions:
+- ext/rphonetic/extconf.rb
+extra_rdoc_files: []
+files:
+- Cargo.lock
+- Cargo.toml
+- LICENSE
+- NOTICE
+- README.md
+- ext/rphonetic/Cargo.toml
+- ext/rphonetic/extconf.rb
+- ext/rphonetic/src/lib.rs
+- lib/rphonetic.rb
+- lib/rphonetic/beider_morse.rb
+- lib/rphonetic/caverphone1.rb
+- lib/rphonetic/caverphone2.rb
+- lib/rphonetic/cologne.rb
+- lib/rphonetic/daitch_mokotoff_soundex.rb
+- lib/rphonetic/double_metaphone.rb
+- lib/rphonetic/encoder.rb
+- lib/rphonetic/encoders.rb
+- lib/rphonetic/match_rating_approach.rb
+- lib/rphonetic/metaphone.rb
+- lib/rphonetic/nysiis.rb
+- lib/rphonetic/phonex.rb
+- lib/rphonetic/refined_soundex.rb
+- lib/rphonetic/soundex.rb
+- lib/rphonetic/version.rb
+- sig/rphonetic.rbs
+- sig/rphonetic/beider_morse.rbs
+- sig/rphonetic/caverphone1.rbs
+- sig/rphonetic/caverphone2.rbs
+- sig/rphonetic/cologne.rbs
+- sig/rphonetic/daitch_mokotoff_soundex.rbs
+- sig/rphonetic/double_metaphone.rbs
+- sig/rphonetic/encoder.rbs
+- sig/rphonetic/match_rating_approach.rbs
+- sig/rphonetic/metaphone.rbs
+- sig/rphonetic/nysiis.rbs
+- sig/rphonetic/phonex.rbs
+- sig/rphonetic/refined_soundex.rbs
+- sig/rphonetic/soundex.rbs
+homepage: https://github.com/tzaid/rphonetic-ruby
+licenses:
+- Apache-2.0
+metadata:
+  source_code_uri: https://github.com/tzaid/rphonetic-ruby
+  bug_tracker_uri: https://github.com/tzaid/rphonetic-ruby/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '4.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby bindings for the rphonetic Rust phonetic algorithms
+test_files: []