rphonetic 0.1.0

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/ext/rphonetic/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "rphonetic_ext"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lib]
+name = "rphonetic_ext"
+crate-type = ["cdylib"]
+
+[dependencies]
+magnus = "0.8"
+rphonetic = { version = "=4.0.0", default-features = false }

data/ext/rphonetic/extconf.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("rphonetic/rphonetic_ext") do |config|
+  config.extra_cargo_args = ["--locked"]
+end

data/ext/rphonetic/src/lib.rs

@@ -0,0 +1,275 @@
+use std::panic::{catch_unwind, AssertUnwindSafe};
+use std::path::PathBuf;
+
+use magnus::{function, method, prelude::*, Error, Ruby};
+use rphonetic::{
+    BeiderMorseBuilder, Caverphone1, Caverphone2, Cologne, ConfigFiles, DaitchMokotoffSoundex,
+    DaitchMokotoffSoundexBuilder, DoubleMetaphone, Encoder, LanguageSet, MatchRatingApproach,
+    Metaphone, NameType, Nysiis, Phonex, RefinedSoundex, RuleType, Soundex, SoundexCommons,
+};
+
+struct BeiderConfig {
+    // Own the parsed rules. Build a cheap borrowing engine for each call,
+    // avoiding self-references, leaked rules, and Ruby GC lifetime hazards.
+    files: ConfigFiles,
+    name_type: NameType,
+    rule_type: RuleType,
+    concat: bool,
+    max_phonemes: usize,
+}
+
+impl BeiderConfig {
+    fn builder(&self) -> BeiderMorseBuilder<'_> {
+        BeiderMorseBuilder::new(&self.files)
+            .name_type(self.name_type)
+            .rule_type(self.rule_type)
+            .concat(self.concat)
+            .max_phonemes(self.max_phonemes)
+    }
+}
+
+enum Algorithm {
+    Simple(Box<dyn Encoder + Send>),
+    Double(DoubleMetaphone),
+    Soundex(Soundex),
+    Refined(RefinedSoundex),
+    Daitch(DaitchMokotoffSoundex),
+    Beider(Box<BeiderConfig>),
+}
+
+#[magnus::wrap(class = "RPhonetic::NativeEncoder", free_immediately, size)]
+struct NativeEncoder(Algorithm);
+
+fn argument_error(message: impl Into<String>) -> Error {
+    Error::new(Ruby::get().unwrap().exception_arg_error(), message.into())
+}
+
+fn rule_error(error: rphonetic::PhoneticError) -> Error {
+    let ruby = Ruby::get().unwrap();
+    let module = ruby
+        .class_object()
+        .const_get::<_, magnus::RModule>("RPhonetic")
+        .unwrap();
+    let class = module
+        .const_get::<_, magnus::ExceptionClass>("RuleError")
+        .unwrap();
+    Error::new(class, error.to_string())
+}
+
+// Malformed external rules or unsupported text must never unwind through Ruby.
+fn checked<T>(f: impl FnOnce() -> Result<T, Error>) -> Result<T, Error> {
+    catch_unwind(AssertUnwindSafe(f)).unwrap_or_else(|_| {
+        Err(Error::new(
+            Ruby::get().unwrap().exception_runtime_error(),
+            "rphonetic could not process this input or rule configuration",
+        ))
+    })
+}
+
+fn mapping(value: String) -> Result<[char; 26], Error> {
+    value
+        .chars()
+        .collect::<Vec<_>>()
+        .try_into()
+        .map_err(|_| argument_error("mapping must contain exactly 26 characters (A through Z)"))
+}
+
+impl NativeEncoder {
+    fn simple(name: String) -> Result<Self, Error> {
+        let encoder: Box<dyn Encoder + Send> = match name.as_str() {
+            "Caverphone1" => Box::new(Caverphone1),
+            "Caverphone2" => Box::new(Caverphone2),
+            "Cologne" => Box::new(Cologne),
+            "MatchRatingApproach" => Box::new(MatchRatingApproach),
+            _ => return Err(argument_error("unknown algorithm")),
+        };
+        Ok(Self(Algorithm::Simple(encoder)))
+    }
+
+    fn metaphone(length: Option<usize>) -> Self {
+        Self(Algorithm::Simple(Box::new(Metaphone::new(length))))
+    }
+
+    fn double_metaphone(length: Option<usize>) -> Self {
+        Self(Algorithm::Double(DoubleMetaphone::new(length)))
+    }
+
+    fn nysiis(strict: bool) -> Self {
+        Self(Algorithm::Simple(Box::new(Nysiis::new(strict))))
+    }
+
+    fn phonex(length: usize) -> Self {
+        Self(Algorithm::Simple(Box::new(Phonex::new(length))))
+    }
+
+    fn soundex(value: String, special_case_h_w: bool) -> Result<Self, Error> {
+        Ok(Self(Algorithm::Soundex(Soundex::new(
+            mapping(value)?,
+            special_case_h_w,
+        ))))
+    }
+
+    fn refined_soundex(value: String) -> Result<Self, Error> {
+        Ok(Self(Algorithm::Refined(RefinedSoundex::new(mapping(
+            value,
+        )?))))
+    }
+
+    fn daitch_mokotoff(rules: String, folding: bool) -> Result<Self, Error> {
+        checked(|| {
+            DaitchMokotoffSoundexBuilder::with_rules(&rules)
+                .ascii_folding(folding)
+                .build()
+                .map(|encoder| Self(Algorithm::Daitch(encoder)))
+                .map_err(rule_error)
+        })
+    }
+
+    fn beider_morse(
+        path: String,
+        name: String,
+        rule: String,
+        concat: bool,
+        max: usize,
+    ) -> Result<Self, Error> {
+        let name_type = match name.as_str() {
+            "generic" => NameType::Generic,
+            "ashkenazi" => NameType::Ashkenazi,
+            "sephardic" => NameType::Sephardic,
+            _ => {
+                return Err(argument_error(
+                    "name_type must be :generic, :ashkenazi, or :sephardic",
+                ))
+            }
+        };
+        let rule_type = match rule.as_str() {
+            "approx" => RuleType::Approx,
+            "exact" => RuleType::Exact,
+            _ => return Err(argument_error("rule_type must be :approx or :exact")),
+        };
+        checked(|| {
+            let files = ConfigFiles::new(&PathBuf::from(path)).map_err(rule_error)?;
+            Ok(Self(Algorithm::Beider(Box::new(BeiderConfig {
+                files,
+                name_type,
+                rule_type,
+                concat,
+                max_phonemes: max,
+            }))))
+        })
+    }
+
+    fn validate(&self, value: &str) -> Result<(), Error> {
+        // These upstream implementations index fixed A-Z mapping arrays.
+        if matches!(self.0, Algorithm::Soundex(_) | Algorithm::Refined(_)) && !value.is_ascii() {
+            return Err(argument_error(
+                "Soundex and RefinedSoundex require ASCII input; transliterate the name first",
+            ));
+        }
+        Ok(())
+    }
+
+    fn with_encoder<T>(&self, f: impl FnOnce(&dyn Encoder) -> T) -> T {
+        match &self.0 {
+            Algorithm::Simple(encoder) => f(encoder.as_ref()),
+            Algorithm::Double(encoder) => f(encoder),
+            Algorithm::Soundex(encoder) => f(encoder),
+            Algorithm::Refined(encoder) => f(encoder),
+            Algorithm::Daitch(encoder) => f(encoder),
+            Algorithm::Beider(config) => f(&config.builder().build()),
+        }
+    }
+
+    fn encode(&self, value: String) -> Result<String, Error> {
+        self.validate(&value)?;
+        checked(|| Ok(self.with_encoder(|encoder| encoder.encode(&value))))
+    }
+
+    fn encode_many(&self, values: Vec<String>) -> Result<Vec<String>, Error> {
+        for value in &values {
+            self.validate(value)?;
+        }
+        checked(|| {
+            Ok(self
+                .with_encoder(|encoder| values.iter().map(|value| encoder.encode(value)).collect()))
+        })
+    }
+
+    fn matches(&self, first: String, second: String) -> Result<bool, Error> {
+        self.validate(&first)?;
+        self.validate(&second)?;
+        checked(|| Ok(self.with_encoder(|encoder| encoder.is_encoded_equals(&first, &second))))
+    }
+
+    fn codes(&self, value: String) -> Result<Vec<String>, Error> {
+        checked(|| match &self.0 {
+            Algorithm::Double(encoder) => {
+                let result = encoder.double_metaphone(&value);
+                Ok(vec![result.primary(), result.alternate()])
+            }
+            Algorithm::Daitch(encoder) => Ok(encoder.inner_soundex(&value, true)),
+            _ => Err(argument_error(
+                "this encoder does not expose multiple codes",
+            )),
+        })
+    }
+
+    fn difference(&self, first: String, second: String) -> Result<usize, Error> {
+        self.validate(&first)?;
+        self.validate(&second)?;
+        checked(|| match &self.0 {
+            Algorithm::Soundex(encoder) => Ok(encoder.difference(&first, &second)),
+            Algorithm::Refined(encoder) => Ok(encoder.difference(&first, &second)),
+            _ => Err(argument_error("difference requires a Soundex encoder")),
+        })
+    }
+
+    fn encode_languages(&self, value: String, languages: Vec<String>) -> Result<String, Error> {
+        let selected = if languages == ["any"] {
+            LanguageSet::Any
+        } else {
+            LanguageSet::SomeLanguages(languages.into_iter().collect())
+        };
+        checked(|| match &self.0 {
+            Algorithm::Beider(config) => Ok(config
+                .builder()
+                .build()
+                .encode_with_languages(&value, &selected)),
+            _ => Err(argument_error("languages requires BeiderMorse")),
+        })
+    }
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("RPhonetic")?;
+    let class = module.define_class("NativeEncoder", ruby.class_object())?;
+    class.define_singleton_method("simple", function!(NativeEncoder::simple, 1))?;
+    class.define_singleton_method("metaphone", function!(NativeEncoder::metaphone, 1))?;
+    class.define_singleton_method(
+        "double_metaphone",
+        function!(NativeEncoder::double_metaphone, 1),
+    )?;
+    class.define_singleton_method("nysiis", function!(NativeEncoder::nysiis, 1))?;
+    class.define_singleton_method("phonex", function!(NativeEncoder::phonex, 1))?;
+    class.define_singleton_method("soundex", function!(NativeEncoder::soundex, 2))?;
+    class.define_singleton_method(
+        "refined_soundex",
+        function!(NativeEncoder::refined_soundex, 1),
+    )?;
+    class.define_singleton_method(
+        "daitch_mokotoff",
+        function!(NativeEncoder::daitch_mokotoff, 2),
+    )?;
+    class.define_singleton_method("beider_morse", function!(NativeEncoder::beider_morse, 5))?;
+    class.define_method("encode", method!(NativeEncoder::encode, 1))?;
+    class.define_method("encode_many", method!(NativeEncoder::encode_many, 1))?;
+    class.define_method("matches", method!(NativeEncoder::matches, 2))?;
+    class.define_method("codes", method!(NativeEncoder::codes, 1))?;
+    class.define_method("difference", method!(NativeEncoder::difference, 2))?;
+    class.define_method(
+        "encode_languages",
+        method!(NativeEncoder::encode_languages, 2),
+    )?;
+    Ok(())
+}

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