name_bank 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe2659cbdd15df894e97db3be809f9040aa3d58f4c1a3df0353e977053e59dca
-  data.tar.gz: 9172dafa9ee2f5fab0d51eb0a0eb7c7c127241631c06a9306d5899349ccab83b
+  metadata.gz: 8bdb30000d395f629f88e6a14d346c067b39049295d999c13556ca36145b1923
+  data.tar.gz: a23fc5f83c129d4a1016be83766d4a3e4e496c634254d58ff3b2e8a1df2effd8
 SHA512:
-  metadata.gz: fcbc5f7075593a3da579e91cfaadd1503b976f6457d680b55169d66422826e08e1c6ddc1b37b873444e616a94cf393e4e72524f3f93316dc470c858f0654edbc
-  data.tar.gz: 28de093ee1e8e751d6288d659480e240d40755c63a08fa0e59fe4afd23d1ec8e06198634b94bd3f94e9532c086321da90ef9dee10ea2a02a9ba109f2b67b2405
+  metadata.gz: c93d2d4749bde09cbb3717118e827370acb2f6dcf7227d388e5a84b75273122606b9887b962c1908778f505cac3630a13f40c8054bb02c7837051813c6366020
+  data.tar.gz: 1d176535f0208a680571a2f0156e80425e2adfbe6458ac26f956f06b53d25af41bf328f1bd5eb6b1d7e4d22ff8a58395fba4ba1a3ce09842480226780942183e

data/CHANGELOG.md

@@ -4,6 +4,45 @@ 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.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,9 +157,10 @@ 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`.
@@ -151,6 +178,32 @@ 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
+```
+
 ## 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,18 @@
 # 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
+  # and how a gender maps to its key. Shared by the runtime NameBank and the
   # build-time SplitScripts tool so the key names live in one place.
   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 +22,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,71 @@
+# 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.
+  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)
+      @variant_names[country] ||= yml_basenames(File.join(@data_dir, "variants", country))
+    end
+
+    private
+
+    def country_pools(country)
+      @country_pools[country] ||= begin
+        path = File.join(@data_dir, "countries", "#{country}.yml")
+        raise UnknownCountry, country unless File.exist?(path)
+
+        read(path)
+      end
+    end
+
+    def variant_pools(country, variant)
+      @variant_pools[[country, variant]] ||= begin
+        path = File.join(@data_dir, "variants", country, "#{variant}.yml")
+        raise UnknownVariant, "#{country}/#{variant}" unless File.exist?(path)
+
+        read(path)
+      end
+    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 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.2.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,46 @@ 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.
   def scripts(country:)
-    repository.scripts(country: country)
+    data = @store.pools(country, nil)
+    PoolSchema::KEYS.any? { |k| data[PoolSchema.native_key(k)]&.any? } ? %i[latin native] : %i[latin]
+  end
+
+  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.2.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