name_bank 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8bdb30000d395f629f88e6a14d346c067b39049295d999c13556ca36145b1923
-  data.tar.gz: a23fc5f83c129d4a1016be83766d4a3e4e496c634254d58ff3b2e8a1df2effd8
+  metadata.gz: 6e238aa5013b3c3a8513f0bd233bb7365f7703c6f852270d93044ee424f6df95
+  data.tar.gz: 697fe182bc1222111617ca9dd2803d208cff375aff171b41d42bf32047cef45c
 SHA512:
-  metadata.gz: c93d2d4749bde09cbb3717118e827370acb2f6dcf7227d388e5a84b75273122606b9887b962c1908778f505cac3630a13f40c8054bb02c7837051813c6366020
-  data.tar.gz: 1d176535f0208a680571a2f0156e80425e2adfbe6458ac26f956f06b53d25af41bf328f1bd5eb6b1d7e4d22ff8a58395fba4ba1a3ce09842480226780942183e
+  metadata.gz: 12411b5e09c5e83bcecefc555c7568843832ed4a37c42553d5fc8efef2c1f4699f828731b1ac68c7e5cd1db93fdbc2baf8be34207553f67bb901b9e2fbc05c6f
+  data.tar.gz: f959d2ec630d8d53cf461c22dfa261935e8369e866d95ce513d5e64c86b42082c0c5622ce129d4e41bce9d42a87a7182c82202baa8c842b34b478e34b61ad2ab

data/CHANGELOG.md

@@ -4,6 +4,62 @@ 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.4.0] - 2026-08-16
+
+Many names in one call. Nothing that worked before changes: sampling from the
+existing methods is byte-identical to 0.3.0 over 2830 samples across every
+country, script and variant, and the name data is untouched.
+
+### Added
+- `full_names(country:, gender:, rng:, count:)` draws that many distinct
+  given/family pairs in one call — the shape a database seed needs. No pair
+  repeats; single names do, because only the pair is unique. The guarantee
+  holds within one call, so no state is kept between calls and sampling stays
+  a function of the caller's RNG. `count:` is required, and asking for more
+  pairs than the two pools can form raises the new `NameBank::PoolExhausted`
+  rather than silently returning fewer.
+
+### Fixed
+- README: the first usage example showed a name pair that the seed above it
+  never produces. Every `# =>` in the README is now the value the code actually
+  returns, checked against the shipped pools. The sampling examples under
+  *Scripts* and *Variants* name their seed too, so all of them can be
+  reproduced rather than taken on trust. No code or data changed.
+
+## [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

data/README.md

@@ -27,23 +27,23 @@ gem install name_bank
 ```ruby
 require "name_bank"
 
-rng = Random.new(1234)
+rng = Random.new(10246)
 
 # A full name (given + family) for a country and gender:
 NameBank.full_name(country: "DE", gender: :female, rng: rng)
-# => { firstname: "Sabine", lastname: "Müller" }
+# => { firstname: "Alexandra", lastname: "Werner" }
 
 # Just a given name or a surname:
-NameBank.first_name(country: "IT", gender: :male, rng: rng)   # => "Amor"
-NameBank.last_name(country: "JP", rng: rng)                   # => "Tsuru"
+NameBank.first_name(country: "IT", gender: :male, rng: rng)   # => "Settimio"
+NameBank.last_name(country: "JP", rng: rng)                   # => "Katsuta"
 
 # 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)  # => "ちゃこ"
+NameBank.first_name(country: "JP", gender: :female, rng: rng)                   # => "Misako"
+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"
+NameBank.first_name(country: "US", gender: :male, rng: rng)                               # => "Jonah"
+NameBank.first_name(country: "US", gender: :male, rng: rng, variant: "african_american")  # => "Tyrone"
 
 # List available countries (ISO alpha-2 codes):
 NameBank.countries.size       # => 106
@@ -54,10 +54,38 @@ 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`.
 
+## Many at once
+
+Seeding a table wants many names in one call, and wants them to differ.
+`full_names` draws distinct given/family pairs:
+
+```ruby
+rng = Random.new(24134)
+
+NameBank.full_names(country: "DE", gender: :female, rng: rng, count: 3)
+# => [{ firstname: "Gerlinde", lastname: "Nowak" },
+#     { firstname: "Juliane",  lastname: "Stark" },
+#     { firstname: "Kornelia", lastname: "Lenz" }]
+```
+
+No pair is drawn twice. Single names do recur once the draw is large enough —
+only the pair is unique, which is what a real population looks like. The
+guarantee holds within one call; two calls know nothing of each other.
+
+`count:` is required, because there is no pool of pairs to hand back without
+one. A country can form as many pairs as given names × surnames: 1500 × 1500
+for most, 30 × 30 for the hand-curated `CN` and `UA` pools. Asking for more
+raises rather than quietly returning fewer:
+
+```ruby
+NameBank.full_names(country: "UA", gender: :male, rng: rng, count: 901)
+# => NameBank::PoolExhausted: UA: 901 pairs requested, 900 available
+```
+
 ## 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 —
+Where sampling is not enough — applying your own weighting, drawing single
+names without repeats, 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:
@@ -68,6 +96,11 @@ NameBank.first_names(country: "DE", gender: :female).first(3)  # => ["Nicole", "
 NameBank.last_names(country: "JP", script: :native).first(3)   # => ["佐藤", "鈴木", "田中"]
 ```
 
+For single names without repeats, the pool plus Ruby is the whole answer:
+`pool.sample(200, random: rng)` returns 200 different names, deterministically.
+Note that `Array#sample` returns fewer than asked for rather than complaining
+when the pool is too small — unlike `full_names`, which raises.
+
 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)`.
@@ -153,6 +186,8 @@ Names come in Latin (default) and, for countries with a non-Latin writing
 system, their native script. Pass `script:`:
 
 ```ruby
+rng = Random.new(325089)
+
 NameBank.first_name(country: "RU", gender: :male, rng: rng)                  # => "Dmitry"
 NameBank.first_name(country: "RU", gender: :male, rng: rng, script: :native) # => "Алексей"
 
@@ -163,7 +198,15 @@ 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
 
@@ -171,6 +214,8 @@ Some countries offer an alternate cultural name pool layered on the default.
 Pass `variant:`:
 
 ```ruby
+rng = Random.new(41)
+
 NameBank.first_name(country: "US", gender: :male, rng: rng, variant: "african_american")
 # => "DeShawn"
 
@@ -191,10 +236,11 @@ still catches the two that are genuinely caller mistakes:
 | `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::PoolExhausted` | `StandardError` | `full_names` was asked for more distinct pairs than the pools can form |
 | `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.
+`EmptyPool` and `MalformedPool` cannot occur with the shipped data; they matter
+when you point `NameBank.new(data_dir:)` at pool files of your own.
 
 ```ruby
 begin
@@ -204,6 +250,94 @@ rescue NameBank::UnknownCountry => e
 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

@@ -28,6 +28,11 @@ class NameBank
     include Error
   end
 
+  # More distinct pairs were asked for than the pools can form.
+  class PoolExhausted < StandardError
+    include Error
+  end
+
   # script: was neither :latin nor :native.
   class UnknownScript < ArgumentError
     include Error

data/lib/name_bank/pool_schema.rb

@@ -5,8 +5,13 @@ 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 NameBank 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
     GIVEN_MALE = "firstnames_male"
     GIVEN_FEMALE = "firstnames_female"

data/lib/name_bank/pool_store.rb

@@ -11,6 +11,10 @@ class NameBank
   # 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
@@ -28,27 +32,49 @@ class NameBank
     end
 
     def variants(country)
-      @variant_names[country] ||= yml_basenames(File.join(@data_dir, "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)
-      @country_pools[country] ||= begin
-        path = File.join(@data_dir, "countries", "#{country}.yml")
-        raise UnknownCountry, country unless File.exist?(path)
+      code = resolve(country, countries)
+      raise UnknownCountry, unresolved(country, countries) if code.nil?
 
-        read(path)
-      end
+      @country_pools[code] ||= read(File.join(@data_dir, "countries", "#{code}.yml"))
     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)
+      code = resolve(country, variant_countries)
+      raise UnknownVariant, "#{country}/#{variant}" if code.nil?
 
-        read(path)
-      end
+      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)
@@ -59,6 +85,16 @@ class NameBank
       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)
 

data/lib/name_bank/version.rb

@@ -2,5 +2,5 @@
 
 # Declared as a class, not a module: NameBank itself is one (see lib/name_bank.rb).
 class NameBank
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/name_bank.rb

@@ -27,6 +27,7 @@ class NameBank
     def first_name(...) = default.first_name(...)
     def last_name(...) = default.last_name(...)
     def full_name(...) = default.full_name(...)
+    def full_names(...) = default.full_names(...)
     def first_names(...) = default.first_names(...)
     def last_names(...) = default.last_names(...)
     def countries(...) = default.countries(...)
@@ -53,6 +54,21 @@ class NameBank
     }
   end
 
+  # Distinct given/family pairs, for seeding many rows at once. No pair is drawn
+  # twice; single names do recur, which is what a population looks like. The
+  # guarantee holds within one call — two calls know nothing of each other.
+  # Asking for more pairs than the two pools can form raises PoolExhausted.
+  def full_names(country:, gender:, rng:, count:, variant: nil, script: :latin)
+    firsts = first_names(country: country, gender: gender, variant: variant, script: script)
+    lasts = last_names(country: country, variant: variant, script: script)
+    available = firsts.size * lasts.size
+    raise PoolExhausted, "#{country}: #{count} pairs requested, #{available} available" if count > available
+
+    distinct_indices(available, count, rng).map do |index|
+      { firstname: firsts[index / lasts.size], lastname: lasts[index % lasts.size] }
+    end
+  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)
@@ -71,13 +87,28 @@ class NameBank
   end
 
   # The script forms this country offers, not writing systems — see CONTEXT.md.
-  def scripts(country:)
-    data = @store.pools(country, nil)
+  # 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
 
   private
 
+  # Partial Fisher-Yates over the space of pair indices, with the swaps kept in
+  # a Hash so that the untouched majority of a two-million-pair space is never
+  # built. Drawing every pair a country has takes count steps; drawing at random
+  # until enough distinct pairs turn up would stall on the last few.
+  def distinct_indices(available, count, rng)
+    swapped = {}
+    Array.new(count) do |drawn|
+      index = rng.rand(drawn...available)
+      picked = swapped.fetch(index, index)
+      swapped[index] = swapped.fetch(drawn, drawn)
+      picked
+    end
+  end
+
   def pool(country, variant, key, script)
     names = names_for_script(@store.pools(country, variant), key, script)
     raise EmptyPool, "#{country}/#{script}" if names.empty?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: name_bank
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Patrick Bartels