rphonetic 0.1.0-x86_64-linux-gnu

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 449b6e953aaeceb66556800ba593ea8c7f2d5dc49d6cd07b3561ece6cfb519f2
+  data.tar.gz: 4c2410c33c212c88395b90e4c98a378c3efc58e761a4a65bc1a01b1eb1b44f39
+SHA512:
+  metadata.gz: 79083d4036915a24f70d482efa7a744515e73db51bbae0cb8218619dbe88f02cde5397a2804a4236ff70e721a94724c25ecffc7083dde46de014030ffff79dc6
+  data.tar.gz: 7514b23c7142251d4400f35178c56ea85d198b2b0c95a5eaec9d388d35465abec58e1c92f209fe35528fb2bacf7e8a743f7c1382a27157fb2af3dd7e0d083e93

data/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/NOTICE

@@ -0,0 +1,17 @@
+rphonetic Ruby bindings
+Copyright 2026 Tariq
+
+This project uses the rphonetic Rust crate by dalvany and Crabe de France,
+licensed under Apache-2.0: https://github.com/Dalvany/rphonetic
+
+The Rust implementation derives from Apache Commons Codec.
+Apache Commons Codec
+Copyright 2002-2020 The Apache Software Foundation
+This product includes software developed at The Apache Software Foundation
+(https://www.apache.org/).
+The Beider-Morse implementation derives from work by
+Copyright (c) 2008 Alexander Beider & Stephen P. Morse.
+
+Test fixtures under spec/fixtures are derived from Apache Commons Codec 1.15
+via rphonetic 3.0.6. They are licensed under Apache-2.0 and are not included
+in the distributed gems. See spec/fixtures/NOTICE for upstream attribution.

data/README.md

@@ -0,0 +1,189 @@
+# rphonetic
+
+Ruby bindings for all twelve algorithms in the [rphonetic Rust crate](https://github.com/Dalvany/rphonetic).
+The wrapper pins rphonetic 4.0.0 and uses Magnus. Supports CRuby 3.4 and 4.0.
+
+## Installation
+
+```ruby
+gem "rphonetic", "~> 0.1.0"
+```
+
+Build a local source gem with
+`bundle exec rake build`. Installing the source gem needs Rust and a C toolchain.
+The included CI workflow builds platform gems for Linux glibc (x64/ARM64),
+macOS (Intel/Apple Silicon), and Windows x64 UCRT, with binaries for Ruby
+3.4 and 4.0 in each package. Those packages require no Rust toolchain
+at installation. CI verifies builds and installed gems on each supported target.
+Linux builds target glibc 2.35 or newer; Alpine/musl is not included.
+
+## API
+
+Every encoder provides `encode(string)`, `encode_many(array)`, and
+`match?(first, second)`. There are also class-level `encode` and `encode_many`
+conveniences, which construct an encoder per call. Reuse instances when encoding
+many names, especially when rules need parsing.
+
+```ruby
+require "rphonetic"
+
+encoder = RPhonetic::DoubleMetaphone.new(max_length: 4)
+encoder.encode("Smith")                     # => "SM0"
+encoder.codes("Smith")                      # => ["SM0", "XMT"]
+encoder.alternate("Smith")                  # => "XMT"
+encoder.encode_many(["Smith", "Schmidt"])    # => ["SM0", "XMT"]
+RPhonetic::DoubleMetaphone.codes("Smith")     # => ["SM0", "XMT"]
+RPhonetic::Soundex.encode("Robert")           # => "R163"
+```
+
+`encode` consistently returns the upstream primary/single code as a String.
+For Double Metaphone, `codes` always returns two strings, including duplicates
+when primary and alternate are identical. For Daitch–Mokotoff, `codes` returns
+all branching codes as an Array. Beider–Morse returns the upstream expression
+string, preserving its parentheses, alternatives, and word groupings.
+
+| Class under `RPhonetic` | Constructor options | Additional methods |
+| --- | --- | --- |
+| `Caverphone1` | None | |
+| `Caverphone2` | None | |
+| `Cologne` | None | |
+| `MatchRatingApproach` | None | |
+| `Metaphone` | `max_length: 4` (`nil` for unlimited) | |
+| `DoubleMetaphone` | `max_length: 4` (`nil` for unlimited) | `codes`, `alternate` |
+| `Nysiis` | `strict: true` | |
+| `Phonex` | `max_length: 4` | |
+| `Soundex` | `mapping: DEFAULT_MAPPING`, `special_case_h_w: true` | `difference` |
+| `RefinedSoundex` | `mapping: DEFAULT_MAPPING` | `difference` |
+| `DaitchMokotoffSoundex` | Required `rules:`, `ascii_folding: true` | `codes` |
+| `BeiderMorse` | Required `rules_path:`, `name_type: :generic`, `rule_type: :approx`, `concat: true`, `max_phonemes: 20` | `encode(value, languages: nil)` |
+
+Lengths must be positive integers; only Metaphone and Double Metaphone support
+`nil`. Custom Soundex mappings contain 26 characters, corresponding to A–Z.
+`Soundex::GENEALOGY_MAPPING` is also available. `difference` counts matching
+positions in the codes. `match?` delegates to the crate: it compares primary
+codes for Double Metaphone and uses the rating algorithm for Match Rating
+Approach. To match either Double Metaphone code, compare the nonempty codes:
+
+```ruby
+left = encoder.codes("Smith").reject(&:empty?)
+right = encoder.codes("Schmidt").reject(&:empty?)
+left.intersect?(right) # => true
+```
+
+## External rules
+
+No default rule files are embedded in or shipped with the gem. Supply compatible
+[Apache Commons Codec 1.15 rule data](https://github.com/apache/commons-codec/tree/rel/commons-codec-1.15/src/main/resources/org/apache/commons/codec/language)
+with your application; the gem never downloads rules automatically.
+
+```ruby
+dm = RPhonetic::DaitchMokotoffSoundex.new(rules: File.read("config/dmrules.txt"))
+dm.codes("Rosochowaciec")
+# => ["944744", "944745", "944754", "944755", "945744", "945745", "945754", "945755"]
+
+bm = RPhonetic::BeiderMorse.new(rules_path: "config/bm")
+bm.encode("Smith")                        # guess languages
+bm.encode("Smith", languages: ["english"])
+bm.encode("Smith", languages: :any)
+```
+
+Beider–Morse needs the complete configuration directory, including files
+referenced by other rules. `name_type` accepts `:generic`, `:ashkenazi`, or
+`:sephardic`; `rule_type` accepts `:approx` or `:exact`. Language names must be
+supported by the supplied rules. Both encoders parse their rules at construction
+and own the parsed data. Files can be removed afterward without affecting an
+existing encoder. Missing/malformed rules normally raise `RPhonetic::RuleError`.
+An upstream panic is caught and surfaced as `RuntimeError`.
+
+## Text and threading
+
+Inputs must be valid Ruby Strings and are transcoded to UTF-8. No automatic
+transliteration is performed. Soundex and RefinedSoundex require ASCII input
+because their upstream implementations use A–Z mapping tables. Other algorithms
+retain upstream handling of non-ASCII text; they are not universal multilingual
+phonetic encoders. Encoding currently holds Ruby's GVL; `encode_many` reduces
+boundary crossings but does not enable parallel Ruby threads.
+
+## Development
+
+All public classes and methods have YARD documentation. RBS signatures live in
+`sig/` and ship with both source and platform gems. Type checkers using the gem's
+signatures can load them with `library "rphonetic"` (for example in a Steepfile).
+Signatures describe constructor keywords, inherited class conveniences, and
+Double Metaphone's `[String, String]` result. Constraints such as positive lengths
+and nonempty language arrays are checked at runtime.
+
+Generate HTML API documentation with `bundle exec rake docs` (open
+`doc/index.html`) and validate signatures with `bundle exec rake rbs`.
+
+Install Rust, Ruby 3.4 or 4.0, a C compiler and libclang, then:
+
+```sh
+bundle install
+bundle exec rake spec
+cargo fmt --check
+cargo clippy --locked -- -D warnings
+bundle exec rake build
+```
+
+`Cargo.lock` is included in source releases for reproducible dependency versions.
+The RSpec suite lives in `spec/`. `bundle exec rake spec` compiles the extension
+before running the suite; `bundle exec rspec` runs it using an existing build.
+`bundle exec rake test` remains an alias for `spec`. CI runs the same specs
+against installed platform gems from outside the checkout, so RSpec's local
+load path cannot accidentally select the source copy.
+The Apache rule fixtures are used only by specs and excluded from all gems.
+
+The [CI workflow](https://github.com/tzaid/rphonetic-ruby/actions/workflows/ci.yml)
+compiles and tests each OS/CPU/Ruby combination,
+combines the two Ruby binaries into each platform gem, then installs and
+loads the packaged gem on each target. The package job uses Ruby 3.4 only to
+assemble the archive; it includes the binaries compiled separately for both
+Ruby versions. It uploads gem artifacts; it does not
+publish to RubyGems. To assemble a platform package manually, place genuine
+target binaries in `lib/rphonetic/{3.4,4.0}/rphonetic_ext.<DLEXT>` and run:
+
+```sh
+ruby script/package.rb --platform arm64-darwin
+```
+
+Never label a binary for an OS, CPU, or Ruby version it was not compiled for.
+For local package verification with a single Ruby installation, run
+`ruby script/stage_binary.rb`, then add `--ruby-abi 3.4` (or your supported
+Ruby series) to the package command. This restricts the gem's Ruby requirement
+to that series. Release CI packages both ABIs.
+
+## Publishing
+
+The `Release` workflow runs when a `v*` tag is pushed. The tag must match
+`RPhonetic::VERSION` (for example, `v0.1.0`). It calls the full CI workflow,
+then verifies and publishes the exact six tested packages using RubyGems
+Trusted Publishing. Branch pushes and pull requests only run CI.
+
+For the first release, configure a pending trusted publisher on RubyGems with
+gem name `rphonetic`, repository owner `tzaid`, repository name `rphonetic-ruby`,
+workflow filename `release.yml`, and environment `release`. The optional
+Workflow Repository fields stay blank. No RubyGems API key is needed.
+
+Once the publisher is configured and release changes are committed and pushed:
+
+```sh
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+Published package versions cannot be overwritten. If publishing stops after
+only some packages are uploaded, inspect the RubyGems release before retrying.
+
+## Versioning
+
+The gem uses independent, three-part semantic versions, starting at `0.1.0`.
+Before `1.0.0`, minor releases may introduce breaking API changes; patch releases
+preserve compatibility. Use `~> 0.1.0` to stay on the `0.1` release series.
+Upstream crate updates are assessed by their effect on Ruby consumers rather
+than by copying the crate's version number. Gem `0.1.0` wraps rphonetic `4.0.0`.
+
+## License
+
+Apache-2.0. See LICENSE and NOTICE. Upstream test fixture attribution is in
+`spec/fixtures/NOTICE`.

data/lib/rphonetic/beider_morse.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RPhonetic
+  # Beider–Morse phonetic matching with caller-supplied configuration files.
+  # Results are expression strings preserving alternatives, parentheses, and
+  # word groupings. {#match?} compares complete expression strings.
+  #
+  # The full rules directory is parsed at construction and owned by the
+  # instance; later changes to those files do not affect it. No rules are
+  # bundled. Inherited {.encode}, {.encode_many}, and {#encode_many} guess
+  # languages for each name; use {#encode} to select languages explicitly.
+  #
+  # @example
+  #   encoder = RPhonetic::BeiderMorse.new(rules_path: "config/bm")
+  #   encoder.encode("Smith", languages: ["english"])
+  class BeiderMorse < Encoder
+    # Load a complete Apache Commons Codec Beider–Morse rules directory.
+    # Referenced rule files must also be present.
+    #
+    # @param rules_path [String] path to the configuration directory
+    # @param name_type [Symbol, String] generic, ashkenazi, or sephardic
+    # @param rule_type [Symbol, String] approx or exact
+    # @param concat [Boolean] whether to encode words together instead of separately
+    # @param max_phonemes [Integer] positive limit on generated phonemes
+    # @raise [RuleError] if files cannot be read or rule parsing fails
+    # @raise [TypeError] if rules_path is not a String
+    # @raise [ArgumentError] if an option has an invalid value
+    # @raise [RuntimeError] if the upstream parser panics
+    def initialize(rules_path:, name_type: :generic, rule_type: :approx, concat: true, max_phonemes: 20)
+      @native = NativeEncoder.beider_morse(
+        text(rules_path), name_type.to_s, rule_type.to_s,
+        boolean(concat, :concat), length_option(max_phonemes, :max_phonemes)
+      )
+    end
+
+    # Encode a name with guessed or explicitly selected languages.
+    # Language names must be supported by the supplied configuration.
+    # This keyword is available only on the instance method.
+    #
+    # @param value [String] name to encode
+    # @param languages [nil, :any, Array<String>] nil guesses languages; :any uses catch-all rules; a nonempty array selects language names
+    # @return [String] phonetic expression including alternatives and word groupings
+    # @raise [ArgumentError] if languages is not nil, :any, or a nonempty Array
+    # @raise [TypeError, ArgumentError, EncodingError, RuntimeError] for the same input or upstream errors as Encoder#encode
+    def encode(value, languages: nil)
+      return super(value) if languages.nil?
+      unless languages == :any || (languages.is_a?(Array) && !languages.empty?)
+        raise ArgumentError, "languages must be nil, :any, or a nonempty Array of language names"
+      end
+      selected = languages == :any ? ["any"] : languages.map { |language| text(language) }
+      @native.encode_languages(text(value), selected)
+    end
+  end
+end

data/lib/rphonetic/caverphone1.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RPhonetic
+  # The original Caverphone algorithm for English names, developed for
+  # New Zealand pronunciation. Codes contain six characters, padded with `1`.
+  #
+  # @example
+  #   RPhonetic::Caverphone1.encode("Thompson") # => "TMPSN1"
+  class Caverphone1 < Encoder
+    # Create a Caverphone1 encoder. This algorithm has no configuration options.
+    def initialize
+      @native = NativeEncoder.simple("Caverphone1")
+    end
+  end
+end

data/lib/rphonetic/caverphone2.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RPhonetic
+  # The revised Caverphone algorithm for English names. Codes contain ten
+  # characters, padded with `1`.
+  #
+  # @example
+  #   RPhonetic::Caverphone2.encode("Thompson") # => "TMPSN11111"
+  class Caverphone2 < Encoder
+    # Create a Caverphone2 encoder. This algorithm has no configuration options.
+    def initialize
+      @native = NativeEncoder.simple("Caverphone2")
+    end
+  end
+end

data/lib/rphonetic/cologne.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RPhonetic
+  # Cologne phonetics (Kölner Phonetik) for German names, including umlauts.
+  # Returns a variable-length numeric code.
+  #
+  # @example
+  #   RPhonetic::Cologne.encode("müller") # => "657"
+  class Cologne < Encoder
+    # Create a Cologne encoder. This algorithm has no configuration options.
+    def initialize
+      @native = NativeEncoder.simple("Cologne")
+    end
+  end
+end

data/lib/rphonetic/daitch_mokotoff_soundex.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module RPhonetic
+  # Daitch–Mokotoff Soundex encodes names using caller-supplied rules.
+  # Inherited {#encode} returns one nonbranching code; {#codes} returns all
+  # branching six-digit codes. {#match?} compares the nonbranching codes.
+  # Rules are parsed once and owned by the instance. No rules are bundled.
+  #
+  # @example
+  #   encoder = RPhonetic::DaitchMokotoffSoundex.new(rules: File.read("config/dmrules.txt"))
+  #   encoder.codes("Rosochowaciec")
+  class DaitchMokotoffSoundex < Encoder
+    # Parse rule text and create a reusable Daitch–Mokotoff encoder.
+    # The rules must use the Apache Commons Codec rule format.
+    #
+    # @param rules [String] complete rule contents, not a file path
+    # @param ascii_folding [Boolean] whether to apply the folding substitutions defined in the rules
+    # @raise [RuleError] if rule parsing fails
+    # @raise [TypeError] if rules is not a String
+    # @raise [ArgumentError] if ascii_folding is not true or false
+    # @raise [RuntimeError] if the upstream parser panics
+    def initialize(rules:, ascii_folding: true)
+      @native = NativeEncoder.daitch_mokotoff(text(rules), boolean(ascii_folding, :ascii_folding))
+    end
+
+    # Return all codes generated by branching rules.
+    #
+    # @param value [String] name to encode
+    # @return [Array<String>] the distinct six-digit codes in upstream order
+    # @raise [TypeError, ArgumentError, EncodingError, RuntimeError] for the same input or upstream errors as #encode
+    def codes(value)
+      @native.codes(text(value))
+    end
+  end
+end

data/lib/rphonetic/double_metaphone.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RPhonetic
+  # Double Metaphone produces primary and alternate phonetic codes.
+  # Inherited {#encode} and {#match?} use only the primary code. Use {#codes}
+  # when comparing names across both pronunciations.
+  #
+  # @example
+  #   RPhonetic::DoubleMetaphone.codes("Smith") # => ["SM0", "XMT"]
+  class DoubleMetaphone < Encoder
+    # Create a Double Metaphone encoder.
+    #
+    # @param max_length [Integer, nil] positive maximum length of each code; nil removes the limit
+    # @raise [ArgumentError] if max_length is neither positive nor nil
+    def initialize(max_length: 4)
+      @native = NativeEncoder.double_metaphone(length_option(max_length, :max_length, unlimited: true))
+    end
+
+    # Construct an encoder and return both codes for one name.
+    #
+    # @param value [String] name to encode
+    # @param options [Hash] constructor keywords
+    # @option options [Integer, nil] :max_length (4) positive maximum code length; nil removes the limit
+    # @return [Array(String, String)] primary and alternate codes, in that order
+    # @see #codes
+    # @see #initialize
+    def self.codes(value, **options)
+      new(**options).codes(value)
+    end
+
+    # Return the primary and alternate codes.
+    # The result always contains two strings, even when the codes are identical
+    # or empty. Both codes respect the configured max_length.
+    #
+    # @param value [String] name to encode
+    # @return [Array(String, String)] primary and alternate codes, in that order
+    # @raise [TypeError, ArgumentError, EncodingError, RuntimeError] for the same input or upstream errors as #encode
+    def codes(value)
+      @native.codes(text(value))
+    end
+
+    # Return only the alternate code.
+    #
+    # @param value [String] name to encode
+    # @return [String] alternate code, possibly identical to the primary code or empty
+    # @raise [TypeError, ArgumentError, EncodingError, RuntimeError] for the same input or upstream errors as #encode
+    # @see #codes
+    def alternate(value)
+      codes(value).last
+    end
+  end
+end

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,79 @@
+--- !ruby/object:Gem::Specification
+name: rphonetic
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: x86_64-linux-gnu
+authors:
+- tzaid
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Reusable encoders for all twelve rphonetic algorithms, with caller-supplied
+  rules and precompiled native gem support.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- NOTICE
+- README.md
+- lib/rphonetic.rb
+- lib/rphonetic/3.4/rphonetic_ext.so
+- lib/rphonetic/4.0/rphonetic_ext.so
+- 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: []