name_bank 0.1.6 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe2659cbdd15df894e97db3be809f9040aa3d58f4c1a3df0353e977053e59dca
-  data.tar.gz: 9172dafa9ee2f5fab0d51eb0a0eb7c7c127241631c06a9306d5899349ccab83b
+  metadata.gz: 184aced32d90cfa194129bdb48895055b2738ed7bef92c1c1a42532421e6e4c6
+  data.tar.gz: 6305e8defeb53e8a6bbb2d7fd47e73a41c6e870cd83659dfad56f24a96f3ebd8
 SHA512:
-  metadata.gz: fcbc5f7075593a3da579e91cfaadd1503b976f6457d680b55169d66422826e08e1c6ddc1b37b873444e616a94cf393e4e72524f3f93316dc470c858f0654edbc
-  data.tar.gz: 28de093ee1e8e751d6288d659480e240d40755c63a08fa0e59fe4afd23d1ec8e06198634b94bd3f94e9532c086321da90ef9dee10ea2a02a9ba109f2b67b2405
+  metadata.gz: 4eae078ebdd3bab2e6c3d455d3c783a6d03b5d119c386017c81d76e5ead0312e066cc24911621506b8c3b7637a88f679a1f5b8b1dfd3202427c0f274a3d3ef87
+  data.tar.gz: 3c7ea3d49e618280f40734193e487c61fc5c6a9c762a16925843533099e7e727feb693dd9c22a1453a29d63316c962506199a493f7469a898ef559f5f5f3020a

data/CHANGELOG.md

@@ -4,6 +4,79 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-08-11
+
+Lookup, documentation and one platform bug. Sampling behaviour and the name
+data are unchanged — verified byte-identical over 1415 samples against 0.2.0.
+Nothing that worked before stops working; on Linux, one thing that failed now
+works.
+
+### Added
+- `scripts` takes an optional `variant:`. A variant can offer different script
+  forms from the country it is layered on; previously `scripts(country:)` only
+  ever reported the country's own.
+
+### Fixed
+- Country and variant names now resolve against the directory listing instead
+  of being handed to `File.exist?`, so lookup no longer inherits the
+  filesystem's case-sensitivity. `country: "de"` found `DE.yml` on macOS and
+  raised `UnknownCountry` on Linux; it now finds it on both. An exact match
+  still wins, and names that differ only in case are reported as ambiguous
+  rather than guessed at.
+- README: a pool with no names was documented as raising
+  `NameBank::UnknownScript`. It has raised `NameBank::EmptyPool` since 0.2.0.
+
+### Documented
+- The pool file format: the directory layout `NameBank.new(data_dir:)` expects,
+  which keys a file must carry, how `_native` pools are named, and which
+  failures a malformed file produces. Variant files may carry `_native` pools —
+  supported by the reader since 0.1.4, now stated and covered by a spec.
+- `NameBank::PoolSchema` is now documented in the README and is supported
+  public API: `KEYS`, `GIVEN_MALE`, `GIVEN_FEMALE`, `SURNAMES`, `native_key`
+  and `gender_key`. It shipped before but was described nowhere. Callers
+  building pool files for `NameBank.new(data_dir:)` should address the YAML
+  keys through it. The key names are covered by semantic versioning from here
+  on: renaming one is a breaking change.
+
+## [0.2.0] - 2026-08-08
+
+An interface release. Sampling behaviour and the name data are unchanged — the
+same `country:`, `gender:`, `rng:`, `variant:` and `script:` calls return the
+same names as 0.1.6. What changed is what else the interface offers, and how
+failures are named. Three breaking changes are listed below.
+
+### Added
+- `NameBank.first_names` and `NameBank.last_names` return a country's whole
+  frequency-ordered pool as a frozen array. They take the same `country:`,
+  `gender:`, `variant:` and `script:` options as the samplers.
+- `NameBank` is now a class and can be instantiated: `NameBank.new(data_dir:)`
+  reads pools from a directory of your own. The class-level methods delegate to
+  a default instance over the shipped data.
+
+### Removed
+- **Breaking:** `NameBank.repository` and the `NameBank::Repository` class. The
+  accessor was never documented; everything it offered is on `NameBank` itself,
+  with `firstnames`/`lastnames` renamed to `first_names`/`last_names`.
+
+- `NameBank::MalformedPool`, raised when a pool file is missing a schema key or
+  holds something other than a list. Files are validated once when read.
+- `NameBank::UnknownGender` and `NameBank::EmptyPool`, so every failure the gem
+  can produce has a name. The README now lists all six.
+
+### Changed
+- `variants(country:)` is memoized like `countries`, so repeated calls no longer
+  hit the filesystem.
+- **Breaking:** `NameBank::Error` is now a module mixed into every error rather
+  than their shared superclass. `rescue NameBank::Error` works as before and now
+  covers every failure, including the two argument errors that previously
+  escaped it; each error also keeps its natural superclass, so
+  `rescue ArgumentError` still catches a bad `gender:` or `script:`. Raising or
+  instantiating `NameBank::Error` itself is no longer possible.
+- **Breaking:** `NameBank::UnknownScript` now means what its name says — a
+  `script:` that is neither `:latin` nor `:native`, previously a bare
+  `ArgumentError`. The empty-pool case it used to signal is now
+  `NameBank::EmptyPool`.
+
 ## [0.1.6] - 2026-07-24
 
 Tooling and internals only — no API, data or behaviour change.

data/README.md

@@ -34,18 +34,44 @@ NameBank.full_name(country: "DE", gender: :female, rng: rng)
 # => { firstname: "Sabine", lastname: "Müller" }
 
 # Just a given name or a surname:
-NameBank.first_name(country: "IT", gender: :male, rng: rng)   # => "Giuseppe"
-NameBank.last_name(country: "JP", rng: rng)                   # => "Tanaka"
+NameBank.first_name(country: "IT", gender: :male, rng: rng)   # => "Amor"
+NameBank.last_name(country: "JP", rng: rng)                   # => "Tsuru"
+
+# Latin (default), or the country's native script where it has one:
+NameBank.first_name(country: "JP", gender: :female, rng: rng)                   # => "Sasahara"
+NameBank.first_name(country: "JP", gender: :female, rng: rng, script: :native)  # => "ちゃこ"
+
+# Default pool, or an alternate cultural pool where one exists:
+NameBank.first_name(country: "US", gender: :male, rng: rng)                               # => "Abe"
+NameBank.first_name(country: "US", gender: :male, rng: rng, variant: "african_american")  # => "Roosevelt"
 
 # List available countries (ISO alpha-2 codes):
-NameBank.countries
-# => ["AE", "AF", "AL", ..., "ZA"]
+NameBank.countries.size       # => 106
+NameBank.countries.first(3)   # => ["AE", "AF", "AL"]
 ```
 
 Sampling is uniform over each pool and fully deterministic for a given
 `rng` — the same seed always yields the same name. `gender:` is `:male`
 or `:female`.
 
+## Whole pools
+
+Where sampling one name is not enough — drawing many names without repeats,
+applying your own weighting, or checking what a country actually ships —
+take the pool itself. `first_names` and `last_names` accept the same
+`country:`, `variant:` and `script:` options as the samplers, and return the
+frequency-ordered pool as a frozen array:
+
+```ruby
+NameBank.first_names(country: "DE", gender: :female).size      # => 1500
+NameBank.first_names(country: "DE", gender: :female).first(3)  # => ["Nicole", "Sandra", "Sabine"]
+NameBank.last_names(country: "JP", script: :native).first(3)   # => ["佐藤", "鈴木", "田中"]
+```
+
+Every method shown so far is also available on an instance, which lets you
+point name_bank at your own directory of pool files:
+`NameBank.new(data_dir: "…").first_name(country: "DE", gender: :male, rng: rng)`.
+
 ## Where it fits
 
 A factory_bot factory:
@@ -131,12 +157,21 @@ NameBank.first_name(country: "RU", gender: :male, rng: rng)                  # =
 NameBank.first_name(country: "RU", gender: :male, rng: rng, script: :native) # => "Алексей"
 
 NameBank.scripts(country: "RU")   # => [:latin, :native]
-NameBank.scripts(country: "DE")   # => [:latin]   (Latin is Germany's script)
+NameBank.scripts(country: "DE")   # => [:latin]
 ```
 
+Germany's script is Latin, so `DE` reports `:latin` only.
 `:latin` and `:native` sample from independent pools. For Latin-script countries
 `:native` returns the same (Latin) pool. Requesting a script with no names
-raises `NameBank::UnknownScript`.
+raises `NameBank::EmptyPool`; a `script:` that is neither `:latin` nor
+`:native` raises `NameBank::UnknownScript`.
+
+`scripts` takes an optional `variant:`, because a variant can offer different
+forms from the country it is layered on:
+
+```ruby
+NameBank.scripts(country: "US", variant: "african_american")   # => [:latin]
+```
 
 ## Variants
 
@@ -151,6 +186,120 @@ NameBank.variants(country: "US")   # => ["african_american"]
 NameBank.variants(country: "DE")   # => []
 ```
 
+## Errors
+
+Every error name_bank raises carries `NameBank::Error`, so one `rescue` covers
+the lot. Each also keeps its natural Ruby superclass, so `rescue ArgumentError`
+still catches the two that are genuinely caller mistakes:
+
+| Error | Superclass | Raised when |
+| --- | --- | --- |
+| `NameBank::UnknownGender` | `ArgumentError` | `gender:` is neither `:male` nor `:female` |
+| `NameBank::UnknownScript` | `ArgumentError` | `script:` is neither `:latin` nor `:native` |
+| `NameBank::UnknownCountry` | `StandardError` | no pool file for that country code |
+| `NameBank::UnknownVariant` | `StandardError` | no pool file for that variant |
+| `NameBank::EmptyPool` | `StandardError` | the pool exists but holds no names |
+| `NameBank::MalformedPool` | `StandardError` | a pool file is missing a key, or holds something other than a list |
+
+The last two cannot occur with the shipped data; they matter when you point
+`NameBank.new(data_dir:)` at pool files of your own.
+
+```ruby
+begin
+  NameBank.first_name(country: "ZZ", gender: :male, rng: rng)
+rescue NameBank::UnknownCountry => e
+  warn "no pool for #{e.message}"
+end
+```
+
+## Pool file format
+
+`NameBank.new(data_dir:)` reads pools from a directory of your own. It holds
+two subdirectories:
+
+```
+my_names/
+  countries/
+    DE.yml
+    RU.yml
+  variants/
+    US/
+      african_american.yml
+```
+
+- `countries/<code>.yml` — the basename is what you pass as `country:`, and
+  what `countries` lists.
+- `variants/<code>/<name>.yml` — the basename is what you pass as `variant:`.
+  No directory for a country means `variants(country:)` returns `[]`.
+- Files that do not end in `.yml` are ignored, and codes are not validated
+  against ISO 3166 — any basename works.
+
+Names resolve the same way on every filesystem: an exact match wins, otherwise
+a unique match ignoring case, so `country: "de"` finds `DE.yml` on Linux as
+well as macOS. Two files whose basenames differ only in case are ambiguous, and
+raise `NameBank::UnknownCountry` rather than being guessed at.
+
+A pool file must carry the three keys in `NameBank::PoolSchema::KEYS`, each a
+list. Any of them may have a native-script counterpart under the same key plus
+`_native`:
+
+```yaml
+firstnames_male:   [Dmitry, Ivan]
+firstnames_female: [Anna, Olga]
+lastnames:         [Ivanov, Petrov]
+
+firstnames_male_native: [Дмитрий, Иван]
+lastnames_native:       [Иванов, Петров]
+```
+
+Variant files are validated the same way and need all three keys too. They may
+carry `_native` pools, which `script: :native` will use — the shipped variants
+do not, because the build pipeline strips them.
+
+Missing a required key, or holding something other than a list under it, raises
+`NameBank::MalformedPool` when the file is read. A key that is present but
+empty is accepted at read time and raises `NameBank::EmptyPool` when sampled.
+Any other key is ignored; the shipped files carry `source:`, which nothing
+reads at runtime.
+
+Sampling is uniform over the whole list, so order does not weight anything. It
+is preserved, and visible through `first_names` and `last_names`.
+
+## Pool schema
+
+`NameBank::PoolSchema` names the YAML keys a pool file uses. It is supported
+public API from 0.2.0 on: the constants and their values will not change
+without a version bump. Use it when you build pool files for
+`NameBank.new(data_dir:)`, so you are not typing key names by hand.
+
+```ruby
+NameBank::PoolSchema::KEYS
+# => ["firstnames_male", "firstnames_female", "lastnames"]
+
+NameBank::PoolSchema::GIVEN_MALE     # => "firstnames_male"
+NameBank::PoolSchema::GIVEN_FEMALE   # => "firstnames_female"
+NameBank::PoolSchema::SURNAMES       # => "lastnames"
+```
+
+`KEYS` is frozen and lists the three pools every file must carry. A file may
+also carry a native-script pool for any of them, under the same key with a
+`_native` suffix:
+
+```ruby
+NameBank::PoolSchema.native_key("lastnames")   # => "lastnames_native"
+```
+
+`gender_key` maps a `gender:` argument to its key, and raises
+`NameBank::UnknownGender` for anything else:
+
+```ruby
+NameBank::PoolSchema.gender_key(:female)   # => "firstnames_female"
+NameBank::PoolSchema.gender_key(:x)        # raises NameBank::UnknownGender
+```
+
+Reading a file that is missing one of `KEYS`, or that holds something other
+than a list under it, raises `NameBank::MalformedPool`.
+
 ## Supported countries
 
 106 countries: Afghanistan, Albania, Algeria, Angola, Argentina, Austria,

data/lib/name_bank/errors.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Declared as a class, not a module: NameBank itself is one (see lib/name_bank.rb).
+class NameBank
+  # Mixed into every error this gem raises, so `rescue NameBank::Error` catches
+  # all of them while each error keeps its natural superclass. Errors whose
+  # valid values are a fixed, countable set are ArgumentErrors; errors that
+  # depend on what a data dir happens to hold are not.
+  module Error; end
+
+  # No pool file for this country code.
+  class UnknownCountry < StandardError
+    include Error
+  end
+
+  # No pool file for this variant of this country.
+  class UnknownVariant < StandardError
+    include Error
+  end
+
+  # A pool file is missing a schema key, or holds something other than a list.
+  class MalformedPool < StandardError
+    include Error
+  end
+
+  # The requested pool exists but holds no names.
+  class EmptyPool < StandardError
+    include Error
+  end
+
+  # script: was neither :latin nor :native.
+  class UnknownScript < ArgumentError
+    include Error
+  end
+
+  # gender: was neither :male nor :female.
+  class UnknownGender < ArgumentError
+    include Error
+  end
+end

data/lib/name_bank/pool_schema.rb

@@ -1,11 +1,23 @@
 # frozen_string_literal: true
 
-module NameBank
+require_relative "errors"
+
+# Declared as a class, not a module: NameBank itself is one (see lib/name_bank.rb).
+class NameBank
   # The pool-key schema: the base YAML keys, how native-script keys are named,
-  # and how a gender maps to its key. Shared by the runtime Repository and the
-  # build-time SplitScripts tool so the key names live in one place.
+  # and how a gender maps to its key. One home for the key names, shared by the
+  # runtime NameBank and the build-time SplitScripts tool.
+  #
+  # Supported public API from 0.2.0 on, documented in the README — callers
+  # building pool files for NameBank.new(data_dir:) address them through here.
+  # The constants and their values are therefore covered by semantic
+  # versioning: changing a key name is a breaking change.
   module PoolSchema
-    KEYS = %w[firstnames_male firstnames_female lastnames].freeze
+    GIVEN_MALE = "firstnames_male"
+    GIVEN_FEMALE = "firstnames_female"
+    SURNAMES = "lastnames"
+
+    KEYS = [GIVEN_MALE, GIVEN_FEMALE, SURNAMES].freeze
 
     module_function
 
@@ -15,9 +27,9 @@ module NameBank
 
     def gender_key(gender)
       case gender
-      when :male then "firstnames_male"
-      when :female then "firstnames_female"
-      else raise ArgumentError, "gender must be :male or :female, got #{gender.inspect}"
+      when :male then GIVEN_MALE
+      when :female then GIVEN_FEMALE
+      else raise UnknownGender, "gender must be :male or :female, got #{gender.inspect}"
       end
     end
   end

data/lib/name_bank/pool_store.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+require_relative "errors"
+require_relative "pool_schema"
+
+# Declared as a class, not a module: NameBank itself is one (see lib/name_bank.rb).
+class NameBank
+  # Everything that touches the filesystem: reading pool files, checking their
+  # shape against PoolSchema, memoizing them, and listing what a data dir holds.
+  # NameBank itself never opens a file. Files are read once per instance, and
+  # validated once when read rather than on every pool access.
+  #
+  # Country and variant names are resolved against the directory listing rather
+  # than handed to File.exist?, so the result does not depend on whether the
+  # filesystem happens to be case-sensitive.
+  class PoolStore
+    def initialize(data_dir)
+      @data_dir = data_dir
+      @country_pools = {}
+      @variant_pools = {}
+      @variant_names = {}
+    end
+
+    def pools(country, variant)
+      variant ? variant_pools(country, variant) : country_pools(country)
+    end
+
+    def countries
+      @countries ||= yml_basenames(File.join(@data_dir, "countries"))
+    end
+
+    def variants(country)
+      code = resolve(country, variant_countries)
+      return [] if code.nil?
+
+      @variant_names[code] ||= yml_basenames(File.join(@data_dir, "variants", code))
+    end
+
+    private
+
+    # An exact match wins; otherwise a unique case-insensitive one; otherwise
+    # nil, because guessing between DE and de would be worse than refusing.
+    def resolve(name, candidates)
+      return name if candidates.include?(name)
+
+      hits = matches(name, candidates)
+      hits.size == 1 ? hits.first : nil
+    end
+
+    def matches(name, candidates)
+      candidates.select { |candidate| candidate.casecmp?(name) }
+    end
+
+    # What to put in the error: the name alone when nothing matched, or the
+    # rival spellings when several did.
+    def unresolved(name, candidates)
+      hits = matches(name, candidates)
+      hits.empty? ? name : "#{name} matches #{hits.join(", ")}"
+    end
+
+    def country_pools(country)
+      code = resolve(country, countries)
+      raise UnknownCountry, unresolved(country, countries) if code.nil?
+
+      @country_pools[code] ||= read(File.join(@data_dir, "countries", "#{code}.yml"))
+    end
+
+    def variant_pools(country, variant)
+      code = resolve(country, variant_countries)
+      raise UnknownVariant, "#{country}/#{variant}" if code.nil?
+
+      name = resolve(variant, variants(code))
+      raise UnknownVariant, "#{country}/#{unresolved(variant, variants(code))}" if name.nil?
+
+      @variant_pools[[code, name]] ||= read(File.join(@data_dir, "variants", code, "#{name}.yml"))
+    end
+
+    def read(path)
+      data = YAML.safe_load_file(path)
+      PoolSchema::KEYS.each do |key|
+        raise MalformedPool, "#{path}: #{key} must be a list of names" unless data[key].is_a?(Array)
+      end
+      data
+    end
+
+    def variant_countries
+      @variant_countries ||= subdirectories(File.join(@data_dir, "variants"))
+    end
+
+    def subdirectories(dir)
+      return [] unless Dir.exist?(dir)
+
+      Dir.children(dir).select { |child| File.directory?(File.join(dir, child)) }.sort
+    end
+
+    def yml_basenames(dir)
+      return [] unless Dir.exist?(dir)
+
+      Dir.children(dir).select { |f| f.end_with?(".yml") }
+        .map { |f| File.basename(f, ".yml") }.sort
+    end
+  end
+
+  private_constant :PoolStore
+end

data/lib/name_bank/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
-module NameBank
-  VERSION = "0.1.6"
+# Declared as a class, not a module: NameBank itself is one (see lib/name_bank.rb).
+class NameBank
+  VERSION = "0.3.0"
 end

data/lib/name_bank.rb

@@ -1,28 +1,49 @@
 # frozen_string_literal: true
 
 require_relative "name_bank/version"
+require_relative "name_bank/errors"
 require_relative "name_bank/pool_schema"
-require_relative "name_bank/repository"
+require_relative "name_bank/pool_store"
 
 # Authentic, gender-matched given names and surnames for 106 countries,
 # addressed by ISO alpha-2 country code. Sampling is uniform and deterministic
 # from a caller-supplied RNG — no global locale or random state.
-module NameBank
-  class Error < StandardError; end
-  class UnknownCountry < Error; end
-  class UnknownVariant < Error; end
-  class UnknownScript < Error; end
-
+#
+# The class-level methods delegate to a default instance over the shipped data
+# dir; instantiate with another data_dir to read pools from elsewhere. Country
+# and variant files are read lazily and memoized per instance.
+#
+# Every error raised here is a NameBank::Error; see the README for the list.
+class NameBank
   DATA_DIR = File.expand_path("../data", __dir__)
 
-  module_function
+  # Every class-level method forwards to the default instance, so the signatures
+  # live once — on the instance methods below.
+  class << self
+    def default
+      @default ||= new
+    end
+
+    def first_name(...) = default.first_name(...)
+    def last_name(...) = default.last_name(...)
+    def full_name(...) = default.full_name(...)
+    def first_names(...) = default.first_names(...)
+    def last_names(...) = default.last_names(...)
+    def countries(...) = default.countries(...)
+    def variants(...) = default.variants(...)
+    def scripts(...) = default.scripts(...)
+  end
+
+  def initialize(data_dir: DATA_DIR)
+    @store = PoolStore.new(data_dir)
+  end
 
   def first_name(country:, gender:, rng:, variant: nil, script: :latin)
-    repository.firstnames(country: country, gender: gender, variant: variant, script: script).sample(random: rng)
+    first_names(country: country, gender: gender, variant: variant, script: script).sample(random: rng)
   end
 
   def last_name(country:, rng:, variant: nil, script: :latin)
-    repository.lastnames(country: country, variant: variant, script: script).sample(random: rng)
+    last_names(country: country, variant: variant, script: script).sample(random: rng)
   end
 
   def full_name(country:, gender:, rng:, variant: nil, script: :latin)
@@ -32,19 +53,47 @@ module NameBank
     }
   end
 
+  # The whole frequency-ordered pool, frozen. The name strings stay mutable.
+  def first_names(country:, gender:, variant: nil, script: :latin)
+    pool(country, variant, PoolSchema.gender_key(gender), script)
+  end
+
+  def last_names(country:, variant: nil, script: :latin)
+    pool(country, variant, PoolSchema::SURNAMES, script)
+  end
+
   def countries
-    repository.countries
+    @store.countries
   end
 
   def variants(country:)
-    repository.variants(country: country)
+    @store.variants(country)
+  end
+
+  # The script forms this country offers, not writing systems — see CONTEXT.md.
+  # With a variant, the forms that variant offers, which may differ.
+  def scripts(country:, variant: nil)
+    data = @store.pools(country, variant)
+    PoolSchema::KEYS.any? { |k| data[PoolSchema.native_key(k)]&.any? } ? %i[latin native] : %i[latin]
   end
 
-  def scripts(country:)
-    repository.scripts(country: country)
+  private
+
+  def pool(country, variant, key, script)
+    names = names_for_script(@store.pools(country, variant), key, script)
+    raise EmptyPool, "#{country}/#{script}" if names.empty?
+
+    names.freeze
   end
 
-  def repository
-    @repository ||= Repository.new(data_dir: DATA_DIR)
+  def names_for_script(data, key, script)
+    case script
+    when :latin then data.fetch(key)
+    when :native
+      native = data[PoolSchema.native_key(key)]
+      native && !native.empty? ? native : data.fetch(key)
+    else
+      raise UnknownScript, "script must be :latin or :native, got #{script.inspect}"
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: name_bank
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.3.0
 platform: ruby
 authors:
 - Patrick Bartels
@@ -136,8 +136,9 @@ files:
 - data/variants/US/african_american.yml
 - docs/name-counts.md
 - lib/name_bank.rb
+- lib/name_bank/errors.rb
 - lib/name_bank/pool_schema.rb
-- lib/name_bank/repository.rb
+- lib/name_bank/pool_store.rb
 - lib/name_bank/version.rb
 homepage: https://github.com/roughneck/name_bank
 licenses:

data/lib/name_bank/repository.rb

@@ -1,84 +0,0 @@
-# frozen_string_literal: true
-
-require "yaml"
-
-module NameBank
-  # Lazy, memoized loader of per-country name pools stored as YAML in data_dir.
-  class Repository
-    def initialize(data_dir:)
-      @data_dir = data_dir
-      @countries_cache = {}
-      @variants_cache = {}
-    end
-
-    def firstnames(country:, gender:, variant: nil, script: :latin)
-      pool(load(country, variant), PoolSchema.gender_key(gender), script, country)
-    end
-
-    def lastnames(country:, variant: nil, script: :latin)
-      pool(load(country, variant), "lastnames", script, country)
-    end
-
-    def scripts(country:)
-      data = load(country, nil)
-      PoolSchema::KEYS.any? { |k| data[PoolSchema.native_key(k)]&.any? } ? %i[latin native] : %i[latin]
-    end
-
-    def countries
-      @countries ||= yml_basenames(File.join(@data_dir, "countries"))
-    end
-
-    def variants(country:)
-      yml_basenames(File.join(@data_dir, "variants", country))
-    end
-
-    private
-
-    def pool(data, key, script, country)
-      names = names_for_script(data, key, script)
-      raise UnknownScript, "#{country}/#{script}" if names.nil? || names.empty?
-
-      names
-    end
-
-    def names_for_script(data, key, script)
-      case script
-      when :latin then data.fetch(key)
-      when :native
-        native = data[PoolSchema.native_key(key)]
-        native && !native.empty? ? native : data.fetch(key)
-      else
-        raise ArgumentError, "script must be :latin or :native, got #{script.inspect}"
-      end
-    end
-
-    def load(country, variant)
-      variant ? load_variant(country, variant) : load_country(country)
-    end
-
-    def load_country(country)
-      @countries_cache[country] ||= begin
-        path = File.join(@data_dir, "countries", "#{country}.yml")
-        raise UnknownCountry, country unless File.exist?(path)
-
-        YAML.safe_load_file(path)
-      end
-    end
-
-    def load_variant(country, variant)
-      @variants_cache[[country, variant]] ||= begin
-        path = File.join(@data_dir, "variants", country, "#{variant}.yml")
-        raise UnknownVariant, "#{country}/#{variant}" unless File.exist?(path)
-
-        YAML.safe_load_file(path)
-      end
-    end
-
-    def yml_basenames(dir)
-      return [] unless Dir.exist?(dir)
-
-      Dir.children(dir).select { |f| f.end_with?(".yml") }
-        .map { |f| File.basename(f, ".yml") }.sort
-    end
-  end
-end